coepi_api_0.3.0.yml

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

      x-amazon-apigateway-integration:
        type: aws_proxy
        uri: ${lambda_invoke_arn}
        httpMethod: POST
      responses:
        '200':
          description: The report was submitted successfully
        '400':
          description: Request Parameter Invalid # TBD
        '500':
          description: Internal Server Error


    get:
      summary: Returns a list of reports generated between a timestamp range provided through query paramaters. If no range is provided, the returns all reports for the current day. If only timestampLower is provided, returns all reports in the range [timestampLower, now]. Range cannot be greater than 5 days.
      parameters:
      - in: query
        name: timestampLower
        description: Lower limit timestamp in UTC for which we need the reports. If not provided, returns all reports for current timestamp
        required: false
        schema:
          $ref: '#/components/schemas/Timestamp'
        example: 1585326048
      - in: query
        name: timestampUpper
        description: Upper limit timestamp in UTC for which we need the reports. If not specified, default is the current timestamp
        required: false
        schema:
          $ref: '#/components/schemas/Timestamp'
        example: 1585327048

      x-amazon-apigateway-integration:
        type: aws_proxy
        uri: ${lambda_invoke_arn}
        httpMethod: POST

      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


# 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