definma-api/api/sample.yaml

/samples:
  get:
    summary: all samples in overview
    description: 'Auth: all, levels: read, write, maintain, dev, admin'
    x-doc: returns only samples with status 10  # TODO: methods /samples/new|deleted
    tags:
      - /sample
    responses:
      200:
        description: samples overview
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'api.yaml#/components/schemas/SampleRefs'
      401:
        $ref: 'api.yaml#/components/responses/401'
      500:
        $ref: 'api.yaml#/components/responses/500'
/sample/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  get:
    summary: TODO sample details
    description: 'Auth: all, levels: read, write, maintain, dev, admin'
    x-doc: status handling (accessible (only for maintain/admin))?  # TODO after decision
    tags:
      - /sample
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleDetail'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'
  put:
    summary: change sample
    description: 'Auth: basic, levels: write, maintain, dev, admin <br>Only maintain and admin are allowed to edit samples created by another user'
    x-doc: status is reset to 0 on any changes
    tags:
      - /sample
    security:
        - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: 'api.yaml#/components/schemas/Sample'
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleRefs'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'
  delete:
    summary: delete sample
    description: 'Auth: basic, levels: write, maintain, dev, admin <br>Only maintain and admin are allowed to edit samples created by another user'
    x-doc: sets status to -1, notes and references to this sample are also kept, only note_fields are updated accordingly
    tags:
      - /sample
    security:
      - BasicAuth: []
    responses:
      200:
        $ref: 'api.yaml#/components/responses/Ok'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/new:
  post:
    summary: add sample
    description: 'Auth: basic, levels: write, maintain, dev, admin'
    x-doc: 'Adds status: 0 automatically'
    tags:
      - /sample
    security:
      - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: 'api.yaml#/components/schemas/Sample'
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleRefs'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/notes/fields:
  get:
    summary: list all existing field names for custom notes fields
    description: 'Auth: all, levels: read, write, maintain, dev, admin'
    x-doc: integrity has to be ensured  # TODO: implement mechanism to regularly check note_fields
    tags:
      - /sample
    responses:
      200:
        description: field names and quantity of usage
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                qty:
                  type: number
                  example: 20
      401:
        $ref: 'api.yaml#/components/responses/401'
      500:
        $ref: 'api.yaml#/components/responses/500'