diff --git a/api_definition/README.md b/api_definition/README.md new file mode 100644 index 0000000..c4b21e9 --- /dev/null +++ b/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_.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. \ No newline at end of file diff --git a/api_definition/coepi_0.2.0.yml b/api_definition/coepi_0.2.0.yml new file mode 100644 index 0000000..ecf376a --- /dev/null +++ b/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 + \ No newline at end of file diff --git a/api_definition/coepi_0.3.0.yml b/api_definition/coepi_0.3.0.yml new file mode 100644 index 0000000..82fdc89 --- /dev/null +++ b/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 + \ No newline at end of file