Adding API definition for v0.2.0

api_definition/README.md

@@ -0,0 +1,3 @@
+## CoEpi API definition
+
+This directory consists of CoEpi API model definitions in [Open API specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md). Each definition file describes the specific version of the API in format ***coepi_<version>.yml***. The model definition can be used to test the API calls or edit the models using [swagger editor](http://editor.swagger.io/). It can also be used to auto-generate client and server SDKs.

api_definition/coepi_0.2.0.yml

@@ -0,0 +1,157 @@
+openapi: 3.0.3
+
+info:
+  description: This is the API model for CoEpi Server
+  version: 0.2.0
+  title: CoEpi Server
+  license:
+    name: MIT License
+    url: https://github.com/Co-Epi/data-models/blob/master/LICENSE
+
+servers:
+  - url: https://coepi.wolk.com:8080
+    description: URL Endpoint used for dev/test
+
+paths:
+  /cenreport:
+    post:
+      summary: Submit symptom or infection report
+      description: Users submit symptom / infection reports and reveal the secret CENKey in their application
+
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reportId: # Suggestion: Why is this being passed by the client? Better to be auto-generated by server?
+                  type: string
+                  description: Unique Identifier of the infection report
+                report:
+                  type: string
+                  format: byte # base64 encoded data
+                  description: Content of the infection report. Example, symptoms
+                cenKeys:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/CenKey'
+                  minItems: 1
+                  maxItems: 50000 # TODO: Discuss appropriate value
+                  uniqueItems: true
+              example: 
+                reportId: 1
+                name: "c2V2ZXJlIGZldmVyLGNvdWdoaW5nLGhhcmQgdG8gYnJlYXRoZQ=="
+                cenKeys: [ "2cb87ba2f39a3119e4096cc6e04e68a8","4bb5c242916d923fe3565bd5c6b09dd3" ]
+              required:
+                - report
+                - cenKeys
+
+      responses:
+        '200':
+          description: The report was submitted successfully
+        '400':
+          description: Request Parameter Invalid # TBD
+        '500':
+          description: Internal Server Error
+        default:
+          description: Unexpected Error
+
+
+  /cenreport/{cenkey}: # Suggestion: Should we allow passing a list of CEN keys to reduce roundtrips ?
+    get:
+      summary: Returns a list of reports associated with a CEN Key
+      parameters:
+      - in: path
+        name: cenkey
+        description: CEN Key for which we need to query the reports
+        required: true
+        schema:
+          $ref: '#/components/schemas/CenKey'
+        example: "6d68785abd6f99ea646fd7c775a14a36f7cec7635a76d3b5554908c6c3a09af5"
+      responses:
+        '200':
+          description: List of infection/symptom reports associated with the specified CEN Key
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Report'
+        '400':
+          description: Request Parameter Invalid # TBD
+        '401':
+          description: CEN Key not found
+        '500':
+          description: Internal Server Error
+        default:
+          description: Unexpected Error
+
+
+  /cenkeys/{timestamp}:
+    get:
+      summary: Returns all cenKeys generated between the range [timestamp - 3600, timestamp) # TBD
+      parameters:
+      - in: path
+        name: timestamp
+        description: Timestamp in unix epoch format
+        required: true
+        schema:
+          $ref: '#/components/schemas/Timestamp'
+        example: 1585326048
+      responses:
+        '200':
+          description: A list of CEN keys for the timestamp range specified in the parameter
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CenKey'
+                example: ["67f48de38f35c231e34e533649ecbfeb","b85c4b373adde4c66651ba63aef40f48"]
+        '400':
+          description: Request Parameter Invalid # TBD
+        '500':
+          description: Internal Server Error
+        default:
+          description: Unexpected Error
+
+
+# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
+components:
+  schemas:
+    CenKey:
+      description: Contact Event Number (CEN) published by the mobile device
+      type: string
+      minLength: 5 #TODO: Discuss appropriate value
+      maxLength: 100 #TODO: Discuss appropriate value and also a possibly an expected pattern
+      example: "67f48de38f35c231e34e533649ecbfeb"
+
+    Timestamp:
+      type: integer
+      description: Timestamp in unix epoch format. It is the number of seconds that have elapsed since the Unix epoch, that is the time 00:00:00 UTC on 1 January 1970, minus leap seconds.
+      minimum: 0
+      example: 1585551684
+
+    Report:
+      type: object
+      description: Infection report representing symptoms and/or positive infection incident
+      properties:
+        reportId:
+          type: string
+          description: Unique Identifier of the infection report
+          minLength: 1 #TODO: Discuss appropriate value
+          maxLength: 100 #TODO: Discuss appropriate value and also a possibly an expected pattern (guid ?)
+        report:
+          type: string
+          description: Content of the infection report consisting of symptoms and/or positive infection incident. Base64 encoded
+          format: byte # base64 encoded data
+          minLength: 1
+          maxLength: 10000
+        reportTimestamp:
+          $ref: '#/components/schemas/Timestamp'
+      example:
+        reportId: "6d68785abd6f99ea646fd7c775a14a36f7cec7635a76d3b5554908c6c3a09af5"
+        report: "c2V2ZXJlIGZldmVyLGNvdWdoaW5nLGhhcmQgdG8gYnJlYXRoZQ=="
+        reportTimestamp: 1585326048
+

api_definition/coepi_0.3.0.yml

@@ -0,0 +1,135 @@
+openapi: 3.0.3
+
+info:
+  description: This is the API model for CoEpi Server
+  version: 0.3.0
+  title: CoEpi Server
+  license:
+    name: MIT License
+    url: https://github.com/Co-Epi/data-models/blob/master/LICENSE
+
+servers:
+  - url: https://api.example.com/v3 #TODO: Update once the server is set up and deployed
+    description: URL Endpoint used for dev/test
+
+paths:
+  /cenreport:
+    post:
+      summary: Submit symptom or infection report
+      description: Users submit symptom / infection reports and reveal the secret CENKey in their application
+
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                report:
+                  type: string
+                  format: byte # base64 encoded data
+                  description: Content of the infection report. Example, symptoms
+                cenKeys:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/CenKey'
+                  minItems: 1
+                  maxItems: 10 # TODO: Discuss appropriate value
+                  uniqueItems: true
+              example:
+                report: "c2V2ZXJlIGZldmVyLGNvdWdoaW5nLGhhcmQgdG8gYnJlYXRoZQ=="
+                cenKeys: [ "2cb87ba2f39a3119e4096cc6e04e68a8","4bb5c242916d923fe3565bd5c6b09dd3" ]
+              required:
+                - report
+                - cenKeys
+
+      responses:
+        '200':
+          description: The report was submitted successfully
+        '400':
+          description: Request Parameter Invalid # TBD
+        '500':
+          description: Internal Server Error
+        default:
+          description: Unexpected Error
+
+
+  /cenreport/{timestampLower}/{timestampUpper}:
+    get:
+      summary: Returns a list of reports generated between a timestamp range
+      parameters:
+      - in: path
+        name: timestampLower
+        description: Lower limit timestamp in UTC for which we need the reports
+        required: true
+        schema:
+          $ref: '#/components/schemas/Timestamp'
+        example: 1585326048
+      - in: path
+        name: timestampUpper
+        description: Upper limit timestamp in UTC for which we need the reports. If not specified, default is the current timestamp
+        required: true
+        schema:
+          $ref: '#/components/schemas/Timestamp'
+        example: 1585327048
+      responses:
+        '200':
+          description: List of infection/symptom reports generated during the hour of the specified timestamp
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Report'
+        '400':
+          description: Request Parameter Invalid # TBD
+        '500':
+          description: Internal Server Error
+        default:
+          description: Unexpected Error
+
+
+# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
+components:
+  schemas:
+    CenKey:
+      description: Contact Event Number (CEN) published by the mobile device
+      type: string
+      minLength: 5 #TODO: Discuss appropriate value
+      maxLength: 100 #TODO: Discuss appropriate value and also a possibly an expected pattern
+      example: "67f48de38f35c231e34e533649ecbfeb"
+
+    Timestamp:
+      type: integer
+      description: Timestamp in unix epoch format. It is the number of seconds that have elapsed since the Unix epoch, that is the time 00:00:00 UTC on 1 January 1970, minus leap seconds.
+      minimum: 0
+      example: 1585551684
+
+    Report:
+      type: object
+      description: Infection report representing symptoms and/or positive infection incident
+      properties:
+        reportId:
+          type: string
+          description: Unique Identifier of the infection report
+          minLength: 1 #TODO: Discuss appropriate value
+          maxLength: 100 #TODO: Discuss appropriate value and also a possibly an expected pattern (guid ?)
+        report:
+          type: string
+          description: Content of the infection report consisting of symptoms and/or positive infection incident. Base64 encoded
+          format: byte # base64 encoded data
+          minLength: 1
+          maxLength: 10000
+        cenKeys:
+          type: array
+          description: CEN Keys belonging to the device that publushed the report
+          items:
+            $ref: '#/components/schemas/CenKey'
+        reportTimestamp:
+          $ref: '#/components/schemas/Timestamp'
+      example:
+        reportId: "6d68785abd6f99ea646fd7c775a14a36f7cec7635a76d3b5554908c6c3a09af5"
+        report: "c2V2ZXJlIGZldmVyLGNvdWdoaW5nLGhhcmQgdG8gYnJlYXRoZQ=="
+        cenKeys: [ "2cb87ba2f39a3119e4096cc6e04e68a8","4bb5c242916d923fe3565bd5c6b09dd3" ]
+        reportTimestamp: 1585326048
+