From f91d4a969c96818a192fe483f89f97f08c8c7a17 Mon Sep 17 00:00:00 2001 From: Bhushan Ramnani Date: Sun, 29 Mar 2020 13:35:33 -0700 Subject: [PATCH 1/5] Adding API definition for v0.2.0 --- api_definition/README.md | 3 + api_definition/coepi_0.2.0.yml | 144 +++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 api_definition/README.md create mode 100644 api_definition/coepi_0.2.0.yml 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..ca85a03 --- /dev/null +++ b/api_definition/coepi_0.2.0.yml @@ -0,0 +1,144 @@ +openapi: 3.0.2 +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 + 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 + required: + - reportId + - 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' + + responses: + '200': + description: OK + 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' + + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/CenKey' + '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#referenceObject +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 + + Report: + description: Infection report representing symptoms and/or positive infection incident + type: object + 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 + minLength: 1 + maxLength: 10000 + timestamp: + $ref: '#/components/schemas/Timestamp' + + 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 + \ No newline at end of file From 41451ea765b582a2291a0c964493c3ac97dcfc72 Mon Sep 17 00:00:00 2001 From: Bhushan Ramnani Date: Mon, 30 Mar 2020 00:19:46 -0700 Subject: [PATCH 2/5] Adding API examples --- api_definition/coepi_0.2.0.yml | 47 ++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/api_definition/coepi_0.2.0.yml b/api_definition/coepi_0.2.0.yml index ca85a03..460d500 100644 --- a/api_definition/coepi_0.2.0.yml +++ b/api_definition/coepi_0.2.0.yml @@ -1,4 +1,5 @@ -openapi: 3.0.2 +openapi: 3.0.3 + info: description: This is the API model for CoEpi Server version: 0.2.0 @@ -29,6 +30,7 @@ paths: 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 @@ -36,9 +38,12 @@ paths: $ref: '#/components/schemas/CenKey' minItems: 1 maxItems: 10 # TODO: Discuss appropriate value - uniqueItems: true + uniqueItems: true + example: + reportId: 1 + name: "c2V2ZXJlIGZldmVyLGNvdWdoaW5nLGhhcmQgdG8gYnJlYXRoZQ==" + cenKeys: [ "2cb87ba2f39a3119e4096cc6e04e68a8","4bb5c242916d923fe3565bd5c6b09dd3" ] required: - - reportId - report - cenKeys @@ -63,10 +68,10 @@ paths: required: true schema: $ref: '#/components/schemas/CenKey' - + example: "6d68785abd6f99ea646fd7c775a14a36f7cec7635a76d3b5554908c6c3a09af5" responses: '200': - description: OK + description: List of infection/symptom reports associated with the specified CEN Key content: application/json: schema: @@ -93,16 +98,17 @@ paths: required: true schema: $ref: '#/components/schemas/Timestamp' - + example: 1585326048 responses: '200': - description: OK + 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': @@ -111,7 +117,7 @@ paths: description: Unexpected Error -# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#referenceObject +# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md components: schemas: CenKey: @@ -119,10 +125,17 @@ components: 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: - description: Infection report representing symptoms and/or positive infection incident type: object + description: Infection report representing symptoms and/or positive infection incident properties: reportId: type: string @@ -131,14 +144,14 @@ components: 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 + description: Content of the infection report consisting of symptoms and/or positive infection incident. Base64 encoded + format: byte # base64 excoded data minLength: 1 maxLength: 10000 - timestamp: + reportTimestamp: $ref: '#/components/schemas/Timestamp' - - 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: + reportId: "6d68785abd6f99ea646fd7c775a14a36f7cec7635a76d3b5554908c6c3a09af5" + report: "c2V2ZXJlIGZldmVyLGNvdWdoaW5nLGhhcmQgdG8gYnJlYXRoZQ==" + reportTimestamp: 1585326048 \ No newline at end of file From 66dc6b8d7706a723a3fc3e540ab225ad6b5dbbb6 Mon Sep 17 00:00:00 2001 From: Bhushan Ramnani Date: Mon, 30 Mar 2020 00:32:35 -0700 Subject: [PATCH 3/5] Addressing few comments --- api_definition/coepi_0.2.0.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api_definition/coepi_0.2.0.yml b/api_definition/coepi_0.2.0.yml index 460d500..ecf376a 100644 --- a/api_definition/coepi_0.2.0.yml +++ b/api_definition/coepi_0.2.0.yml @@ -37,7 +37,7 @@ paths: items: $ref: '#/components/schemas/CenKey' minItems: 1 - maxItems: 10 # TODO: Discuss appropriate value + maxItems: 50000 # TODO: Discuss appropriate value uniqueItems: true example: reportId: 1 @@ -145,7 +145,7 @@ components: report: type: string description: Content of the infection report consisting of symptoms and/or positive infection incident. Base64 encoded - format: byte # base64 excoded data + format: byte # base64 encoded data minLength: 1 maxLength: 10000 reportTimestamp: From f508f5851ef181d945c3d1c11e8737f51703d68b Mon Sep 17 00:00:00 2001 From: Bhushan Ramnani Date: Tue, 31 Mar 2020 01:04:06 -0700 Subject: [PATCH 4/5] Adding API definition 1.0.0 --- api_definition/coepi_1.0.0.yml | 128 +++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 api_definition/coepi_1.0.0.yml diff --git a/api_definition/coepi_1.0.0.yml b/api_definition/coepi_1.0.0.yml new file mode 100644 index 0000000..4174ad7 --- /dev/null +++ b/api_definition/coepi_1.0.0.yml @@ -0,0 +1,128 @@ +openapi: 3.0.3 + +info: + description: This is the API model for CoEpi Server + version: 1.0.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/v1 #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/{timestamp}: + get: + summary: Returns a list of reports generated during the hour of the specified timestamp in UTC + parameters: + - in: path + name: timestamp + description: Timestamp for which we need the reports. All the reports that were generated in the specified hour of the timestamp will be retrieved. + required: true + schema: + $ref: '#/components/schemas/Timestamp' + example: 1585326048 + 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 From eae23b88074d9cf29aa69e46c70dd11dab1b67e4 Mon Sep 17 00:00:00 2001 From: Bhushan Ramnani Date: Thu, 2 Apr 2020 21:50:09 -0700 Subject: [PATCH 5/5] Updating 0.3.0 to include timestamp range --- .../{coepi_1.0.0.yml => coepi_0.3.0.yml} | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) rename api_definition/{coepi_1.0.0.yml => coepi_0.3.0.yml} (87%) diff --git a/api_definition/coepi_1.0.0.yml b/api_definition/coepi_0.3.0.yml similarity index 87% rename from api_definition/coepi_1.0.0.yml rename to api_definition/coepi_0.3.0.yml index 4174ad7..82fdc89 100644 --- a/api_definition/coepi_1.0.0.yml +++ b/api_definition/coepi_0.3.0.yml @@ -2,14 +2,14 @@ openapi: 3.0.3 info: description: This is the API model for CoEpi Server - version: 1.0.0 + 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/v1 #TODO: Update once the server is set up and deployed + - url: https://api.example.com/v3 #TODO: Update once the server is set up and deployed description: URL Endpoint used for dev/test paths: @@ -54,17 +54,24 @@ paths: description: Unexpected Error - /cenreport/{timestamp}: + /cenreport/{timestampLower}/{timestampUpper}: get: - summary: Returns a list of reports generated during the hour of the specified timestamp in UTC + summary: Returns a list of reports generated between a timestamp range parameters: - in: path - name: timestamp - description: Timestamp for which we need the reports. All the reports that were generated in the specified hour of the timestamp will be retrieved. + 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