Merge pull request #103 from regulaforensics/feature/add-healthchecks

[SP-18949] Add /healthz and /readyz endpoints

Author: KirylKovaliov

detect.yml

@@ -5,7 +5,7 @@ paths:
       - $ref: './common.yml#/components/parameters/x-request'
     post:
       tags:
-        - matching
+        - match
       summary: "detect and check quality"
       description: "Use the POST `api/detect` endpoint to analyze images, recognize faces in them, and return cropped and aligned portraits of the detected people. 
       

diagnostics.yml

@@ -0,0 +1,54 @@
+openapi: 3.0.3
+
+paths:
+  /healthz:
+    parameters:
+      - $ref: "./common.yml#/components/parameters/x-request"
+    get:
+      summary: "Server healthcheck"
+      operationId: healthz
+      tags:
+        - healthcheck
+      responses:
+        200:
+          description: "Device info"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeviceInfo"
+  /readyz:
+    parameters:
+      - $ref: "./common.yml#/components/parameters/x-request"
+    get:
+      summary: "License healthcheck"
+      operationId: readyz
+      tags:
+        - healthcheck
+      responses:
+        200:
+          description: "License is valid"
+        400:
+          description: "License is not valid"
+
+components:
+  schemas:
+    DeviceInfo:
+      type: object
+      properties:
+        app:
+          type: string
+        licenseId:
+          type: string
+        licenseSerial:
+          type: string
+        licenseValidUntil:
+          type: string
+          format: date-time
+        version:
+          type: string
+      example:
+        app: "Regula Face Recognition Web API"
+        licenseId: "4D43A2AF-E321-496C-9A4E-5A8F3D26DF0E"
+        licenseSerial: "OL70786"
+        licenseValidUntil: "9999-12-31T23:59:59Z"
+        version: "7.5.297907.1721"

healthcheck.yml

@@ -124,7 +124,7 @@ components:
         outputImageParams:
           $ref: "./common.yml#/components/schemas/OutputImageParams"
         detectAll:
-          $ref: "./matching.yml#/components/schemas/detectAll"
+          $ref: "./match.yml#/components/schemas/detectAll"
         threshold:
           type: number
           format: float

identification.yml

@@ -22,11 +22,18 @@ info:
     * [Java](https://github.com/regulaforensics/FaceSDK-web-java-client) client compatible with jvm and android
     * [Python](https://github.com/regulaforensics/FaceSDK-web-python-client) 3.5+ client
     * [C#](https://github.com/regulaforensics/FaceSDK-web-csharp-client) client for .NET & .NET Core
-  x-tagGroups:
-    name: liveness
+
+x-tagGroups:
+  - name: Core
     tags:
-      - liveness
       - match
+      - person
+      - group
+      - search
+      - liveness 2.0
+  - name: Requests
+    tags:
+      - healthcheck
 
 servers:
   - url: http://localhost:41101/
@@ -37,7 +44,7 @@ servers:
 # ~1 means '/'
 paths:
   /api/match:
-    $ref: './matching.yml#/paths/~1match'
+    $ref: './match.yml#/paths/~1match'
   /api/match_and_search:
     $ref: './match_and_search.yml#/paths/~1match_and_search'
   /api/detect:
@@ -62,5 +69,7 @@ paths:
     $ref: './search.yml#/paths/~1search'
   /api/v2/liveness:
     $ref: './liveness.yml#/paths/~1v2~1liveness'
-  /api/readiness:
-    $ref: './diagnostics.yml#/paths/~1readiness'  
+  /api/healthz:
+    $ref: "./healthcheck.yml#/paths/~1healthz"
+  /api/readyz:
+    $ref: "./healthcheck.yml#/paths/~1readyz"

index.yml

@@ -5,7 +5,7 @@ paths:
       - $ref: './common.yml#/components/parameters/x-request'
     post:
       tags:
-        - matching
+        - match
       summary: "compare faces (1:1)"
       description: "To perform a comparison of faces in the same image or in two different images, use POST `/api/match`. It's possible to compare faces in the same image or in two different images, this is defined by the `images.type` parameter. <br><br> The face detection result is displayed in the `detections` field.
 

matching.yml match.ymlmatching.yml renamed to match.yml

@@ -5,9 +5,9 @@ paths:
       - $ref: './common.yml#/components/parameters/x-request'
     post:
       tags:
-        - matching
+        - match
       summary: 'match and search (1:1 + 1:N)'
-      description: "To compare several images from a document and look up a person in the database in one request, use POST `/api/match_and_search`. In this case, the calculation of the descriptor will be performed only once, as opposed to using two requests for the same operation. If only one person is identified, matching is not performed and only search is carried out."
+      description: "To compare several images from a document and look up a person in the database in one request, use POST `/api/match_and_search`. In this case, the calculation of the descriptor will be performed only once, as opposed to using two requests for the same operation. If only one person is identified, match is not performed and only search is carried out."
       operationId: match_and_search
       requestBody:
         required: true
@@ -42,7 +42,7 @@ components:
                   content:
                     $ref: './common.yml#/components/schemas/ImageData'
                   type:
-                    $ref: './matching.yml#/components/schemas/ImageSource'
+                    $ref: './match.yml#/components/schemas/ImageSource'
             groupIds:
               type: array
               description: "IDs of the groups in which the search is performed."
@@ -59,7 +59,7 @@ components:
               type: array
               description: "The match and search results."
               items:
-                $ref: './matching.yml#/components/schemas/MatchImageResult'
+                $ref: './match.yml#/components/schemas/MatchImageResult'
             elapsedTime:
               type: number
               description: "Time the processing has taken, ms."
@@ -81,7 +81,7 @@ components:
                     items:
                       $ref: '#/components/schemas/FacesResponse'
                   imageIndex:
-                    $ref: './matching.yml#/components/schemas/MatchImageIndex'
+                    $ref: './match.yml#/components/schemas/MatchImageIndex'
                   status:
                     $ref: './common.yml#/components/schemas/FaceSDKResultCode'
     PersonWithImages:
@@ -97,7 +97,7 @@ components:
 
     FacesResponse:
       allOf:
-        - $ref: './matching.yml#/components/schemas/DetectionFace'
+        - $ref: './match.yml#/components/schemas/DetectionFace'
         - type: object
           properties:
             persons: