openapi: 3.0.2
info:
  title: RAS-RM Sample Service
  description: A service for dealing with various parties (businesses, survey respondents etc and their enrolments)
  version: "1.0"

servers:
  - url: http://localhost:8125/
    description: The path used by Sample when port forwarded by kubectl (8125:8080)

tags:
  - name: info
    description: Informational endpoints.
  - name: samples
    description: Endpoints for interacting with samples.

paths:
  /actuator/info:
    get:
      summary: Application information
      description: Application information
      tags:
        - info
      responses:
        '200':
          description: High level info about the application.
  /samples/count:
    get:
      summary: Sample unit count.
      description: Sample unit count.
      tags:
        - samples
      responses:
        '200':
          description: Sample Summaries were retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sampleUnitsTotal:
                    type: integer
                    example: 1
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /samples/samplesummaries:
    get:
      summary: List sample summaries.
      description: Retrieve a list of all existing SampleSummaries
      tags:
        - samples
      responses:
        '200':
          description: Sample Summaries were retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SampleSummary'
        '204':
          description: No Sample summaries found
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /samples/samplesummary/{sampleSummaryId}:
    get:
      summary: Get Sample Summary
      description: SampleSummary info for the given sampleSummaryId
      tags:
        - samples
      parameters:
        - in: path
          name: sampleSummaryId
          required: true
          schema:
            type: string
            format: uuid
            example: 34597808-ec88-4e93-af2f-228e33ff7946
      responses:
        '201':
          description: The sample summary was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleUnit'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      summary: Delete sample summary
      description: Delete sample summary and all sample units relating to it
      tags:
        - samples
      responses:
        '204':
          description: Sample summary and sample units were deleted successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /samples/samplesummary/{sampleSummaryId}/check-and-transition-sample-summary-status:
    get:
      summary: Check all sample units present for the sample summary
      description: Checks all present and move to ACTIVE state if true
      tags:
        - samples
      parameters:
        - in: path
          name: sampleSummaryId
          required: true
          schema:
            type: string
            format: uuid
            example: 34597808-ec88-4e93-af2f-228e33ff7946
      responses:
        '200':
          description: The call was successful.  Will return this regardless of whether or not it's ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleSummaryLoadingStatus'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          description: '#/components/responses/ServerError'
    delete:
      summary: Delete sample summary
      description: Delete sample summary and all sample units relating to it
      tags:
        - samples
      responses:
        '204':
          description: Sample summary and sample units were deleted successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /samples/samplesummary:
    post:
      summary: Create sample summary
      description: Create sample summary
      tags:
        - samples
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SampleSummary'
      responses:
        '200':
          description: The sample summary was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleSummary'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /samples/{id}:
    get:
      summary: Get Sample Unit
      description: SampleUnit info for the given ID
      tags:
        - samples
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: 34597808-ec88-4e93-af2f-228e33ff7946
      responses:
        '200':
          description: The sample unit was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleUnit'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /samples/{samplesummaryId}/sampleunits:
    get:
      summary: Get Sample Units from sample summary
      description: Get Sample Units from sample summary
      tags:
        - samples
      parameters:
        - in: path
          name: samplesummaryId
          required: true
          schema:
            type: string
            format: uuid
            example: 34597808-ec88-4e93-af2f-228e33ff7946
        - in: query
          name: state
          description: only return sample units that have the requested state
          required: false
          schema:
            type: string
            example: FAILED
      responses:
        '200':
          description: The sample units were retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SampleUnit'
        '400':
          description: 'No sample unit found for sample summary.'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    post:
      summary: Create Sample Unit for sample summary
      description: Create Sample Unit for sample summary
      tags:
        - samples
      parameters:
        - in: path
          name: samplesummaryId
          required: true
          schema:
            type: string
            format: uuid
            example: 34597808-ec88-4e93-af2f-228e33ff7946
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SampleUnit'
      responses:
        '200':
          description: The sample unit was created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SampleUnit'
        '400':
          description: 'No sample unit found for sample summary.'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: 'Sample already exists for the sample summary with that sampleUnitRef'
        '500':
          description: '#/components/responses/ServerError'
  /samples/{sampleSummaryId}/sampleunits/{sampleUnitRef}:
    get:
      summary: Get Sample Unit
      description: Get sample unit by sampleSummaryId and sampleUnitRef
      tags:
        - samples
      parameters:
        - in: path
          name: sampleSummaryId
          required: true
          schema:
            type: string
            format: uuid
            example: 34597808-ec88-4e93-af2f-228e33ff7946
        - in: path
          name: sampleUnitRef
          required: true
          schema:
            type: string
            example: 49990000001
      responses:
        '200':
          description: The sample unit was found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleUnit'
        '400':
          description: 'No sample unit found'
        '401':
          $ref: '#/components/responses/UnauthorizedError'


components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid.
    MalformedIDError:
      description: The ID provided wasn't a proper UUID.
    NotFoundError:
      description:  Resource has not been found
    InvalidRequestBodyError:
      description: One or more of the fields provided in the RequestBody wasn't part of the schema, wasn't set to a valid value, or the ID provided wasn't a proper UUID.
    ServerError:
      description: Something unexpected happened with the server.
  schemas:
    SampleUnit:
      type: object
      properties:
        formType:
          type: string
          example: "0001"
        id:
          type: string
          format: uuid
          example: 34597808-ec88-4e93-af2f-228e33ff7946
        sampleSummaryFK:
          type: integer
          example: 321
        sampleUnitPK:
          type: integer
          example: 123
        sampleUnitRef:
          type: string
          example: "01234567890"
        sampleUnitType:
          type: string
          example: "01234567890"
        status:
          type: string
          enum: [INIT, DELIVERED, PERSISTED, FAILED]
          example: INIT
    SampleSummary:
      type: object
      properties:
        effectiveEndDateTime:
          type: string
          format: date-time
          example: "2020-06-08T09:50:25.338Z"
        effectiveStartDateTime:
          type: string
          format: date-time
          example: "2020-06-08T09:50:25.338Z"
        errorCode:
          type: string
          enum: [None, NotCsv, DataError, NotSpecified]
          example: NotCsv
        expectedCollectionInstruments:
          type: integer
          example: 0
        id:
          type: string
          format: uuid
          example: fd6a1aa3-ba17-43a8-beae-a39e67c6444d
        ingestDateTime:
          type: string
          format: date-time
          example: "2020-06-08T09:50:25.338Z"
        notes:
          type: string
          example: example
        state:
          type: string
          enum: [ACTIVE, INIT, FAILED]
          example: ACTIVE
        surveyRef:
          type: string
          example: "342"
        totalSampleUnits:
          type: integer
          example: 1
    SampleSummaryLoadingStatus:
      type: object
      properties:
        areAllSampleUnitsLoaded:
          type: boolean
          example: true
        expectedTotal:
          type: integer
          example: 200
        currentTotal:
          type: integer
          example: 150
security:
  - basicAuth: []