openapi: 3.0.1
info:
  title: Data Store (Samples) API
  description: >-
    Provides endpoints for querying and writing data samples for an authenticated user or on behalf of a user via agency
  version: v1
servers:
  - url: 'https://api.{env}.{tenant}.lenushealth.dev/sample/v1'
    variables:
      env:
        default: test
        enum:
          - test
          - sbx
      tenant:
        default: ggc
        enum:
          - ggc
        description: 'Available tenants'
paths:
  /:
    get:
      summary: 'Read health data samples'
      description: 'Query health data samples for the authenticated individual or on behalf of an individual via agency'
      operationId: 'read-samples'
      security:
        - bearer: []
      parameters:
        - name: Types
          description: The specific health data types you wish to query, types must be allowed by your `access_token` i.e. read.*heart_rate* and do not include the operation prefix of _read_ or _write_
          in: query
          schema:
            type: array
            items:
              type: string
            example:
            - heart_rate
            - step_count
        - name: RangeOfStartDate.LowerBound
          in: query
          required: true
          schema:
            type: string
            format: datetime
            example: '2020-01-01T09:00:00'
        - name: RangeOfStartDate.UpperBound
          in: query
          required: true
          schema:
            type: string
            format: datetime
            example: '2020-01-01T09:00:00'
        - name: Skip
          in: query
          description: 'The number of results to skip-over. Defaults to 0'
          required: false
          schema:
            type: number
            example: 0
        - name: Take
          in: query
          description: 'The maximum number of results to return. Defaults to 100, with a maximum of 1000'
          required: false
          schema:
            type: number
            default: 100
        - name: OrderProperty
          in: query
          description: 'The field on which to order query results'
          required: false
          schema:
            type: string
            enum:
            - StartDate
            - EndDate
        - name: OrderDirection
          in: query
          description: 'The order direction of query results'
          required: false
          schema:
            type: string
            enum:
            - Ascending
            - Descending
      responses:
        '200':
          description: 'Data response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/readSampleResultV1'
        '401':
          description: 'The `access_token` is not valid, this maybe due to expiration or invalid audience of issuer'
    post:
      summary: Submit samples to data store
      description: Submits a series of samples to the data store
      operationId: submit-samples
      requestBody:
        $ref: '#/components/requestBodies/submitSampleData'
      security:
        - bearer: []
      responses:
        '200':
          description: 'one or more request validation errors occurred, review the errors and try again'
        '400':
          description: 'Unable to process request due to request validation errors'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpProblemDetails'
        '401':
          description: 'The `access_token` is not valid, this maybe due to expiration or invalid audience of issuer'
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
  requestBodies:
    submitSampleData:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/sampleDataV1'
  schemas:
    httpProblemDetails:
      title: HTTP Problem Details API Response
      externalDocs: 
        description: 'RFC 7807'
        url: https://tools.ietf.org/html/rfc7807
      type: object
      properties:
        type:
          type: string
          example: '#not-found'
        title:
          type: string
        status:
          type: number
          enum:
            - 400
            - 401
            - 403
            - 404
            - 500
        detail:
          type: string
        instance:
          type: string  
    readSampleResultV1:
      title: Read samples result
      type: object
      properties:
        totalAvailable:
          type: number
          example: 1
        count:
          type: number
          example: 1
        datas:
          type: array
          items: 
            $ref: '#/components/schemas/sampleDataV1'
    sampleDataV1:
      title: Sample data structure
      type: object
      properties:
        device:
          type: string
          title: The device string should capture details about the type of device used to measure the Sample. It should not include particular device or user identifiers, see sample data device string documentation for details.
        clientAssignedId:
          type: string
        subject:
          type: string
          format: uuid
        type:
          type: string
        quantityValue:
          type: number
        categoryValue:
          type: string
        correlationObjects: 
          type: object
          example: 
          properties:
            device:
              type: string
            clientAssignedId:
              type: string
            subject:
              type: string
              format: uuid
            type:
              type: string
            quantityValue:
              type: number
            categoryValue:
              type: number
            dateRange:
              type: object
              properties:
                lowerBound:
                  type: string
                  format: datetime
                upperBound:
                  type: string
                  format: datetime                          
        dateRange:
          type: object
          properties:
            lowerBound:
              type: string
              format: datetime
            upperBound:
              type: string
              format: datetime