definma-api/api/sample.yaml

/samples:
  get:
    summary: all samples in overview
    description: 'Auth: all, levels: read, write, dev, admin, spectral data can only be accessed by dev and admin'
    x-doc: 'Limitations: paging and csv output does not work when including the spectrum measurement fields as well as
    the returned number of total samples'
    tags:
      - /sample
    parameters:
      - name: status
        description: 'values: validated|new, for dev/admin also deleted, defaults to validated'
        in: query
        schema:
          type: array
          items:
            type: string
        example: ['validated']
      - name: from-id
        description: first id of the requested page, if not given the results are displayed from start
        in: query
        schema:
          type: string
        example: 5ea0450ed851c30a90e70894
      - name: to-page
        description: 'relative change of pages, use negative values to get back, defaults to 0, works only together with
        page-size'
        in: query
        schema:
          type: string
        example: 1
      - name: page-size
        description: number of items per page
        in: query
        schema:
          type: string
        example: 30
      - name: sort
        description: sorting of results, in format 'key-asc/desc'
        in: query
        schema:
          type: string
        example: color-asc
      - name: fields[]
        description: "the fields to include in the output as array, defaults to ['_id', 'number', 'type',
        'batch', 'material_id', 'color', 'condition', 'note_id', 'user_id', 'added']"
        in: query
        schema:
         type: array
         items:
           type: string
        example: ['number', 'batch']
      - name: filters[]
        description: "the filters to apply as an array of URIComponent encoded objects in the form {mode:
        'eq/ne/lt/lte/gt/gte/in/nin/stringin', field: 'material.m', values: ['15']} using
        encodeURIComponent(JSON.stringify({})) <br>Use {mode: 'eq', field: 'condition', values: [{}]} and
        {mode: 'eq', field: 'measurements', values: [null]} to filter for samples without condition or measurements"
        in: query
        schema:
         type: array
         items:
           type: string
        example: '["%7B%22mode%22%3A%22eq%22%2C%22field%22%3A%22material.m%22%2C%22values%22%3A%5B%2215%22%5D%7D",
        "%7B%22mode%22%3A%22isin%22%2C%22field%22%3A%22material.supplier%22%2C%22values%22%3A%5B%22BASF%22%2C%22DSM%22
        %5D%7D"]'
      - name: output
        description: 'output format, available values are csv, json, flatten (converts material: {number: x} to
        material.number: x), defaults to json'
        in: query
        schema:
          type: boolean
        example: csv
    responses:
      200:
        description: samples overview (output depends on the fields specified)<br>
          if the csv parameter is set, this is in CSV instead of JSON format
        headers:
          x-total-items:
            description: Total number of available items when from-id is not specified and spectrum field is not
              included
            schema:
              type: integer
              example: 243
        content:
          application/json:
            schema:
              type: array
              items:
                $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'

/samples/{state}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/State'
  get:
    summary: all new/deleted samples in overview
    description: 'Auth: basic, levels: admin'
    x-doc: returns only samples with status 0/-1
    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'

/samples/count:
  get:
    summary: total number of samples
    description: 'Auth: all, levels: read, write, dev, admin'
    tags:
      - /sample
    responses:
      200:
        description: sample count
        content:
          application/json:
            schema:
              properties:
                count:
                  type: number
                  example: 864
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  get:
    summary: sample details
    description: 'Auth: all, levels: read, write, dev, admin, spectral data can only be accessed by dev and admin<br>
    Returns validated as well as new measurements'
    x-doc: deleted samples are available only for dev/admin
    tags:
      - /sample
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleDetail'
      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'
  put:
    summary: change sample
    description: 'Auth: basic, levels: write, dev, admin <br>
    Only dev and admin are allowed to edit samples created by another user'
    x-doc: status is reset to 0 on any changes, deleted samples cannot be changed
    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, dev, admin <br>
    Only dev 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/number/{number}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Number'
  get:
    summary: sample details
    description: 'Auth: all, levels: read, write, dev, admin, spectral data can only be accessed by dev and admin<br>
    Returns validated as well as new measurements'
    x-doc: deleted samples are available only for dev/admin
    tags:
      - /sample
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleDetail'
      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/restore/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  put:
    summary: restore sample
    description: 'Auth: basic, levels: dev, admin'
    x-doc: status is set to 0
    tags:
      - /sample
    security:
      - BasicAuth: []
    responses:
      200:
        $ref: 'api.yaml#/components/responses/Ok'
      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/validate/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  put:
    summary: set sample status to validated
    description: 'Auth: basic, levels: dev, admin'
    x-doc: status is set to 10
    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, dev, admin.   Number property is only for admin when adding existing
    samples'
    x-doc: 'Adds status: 0 automatically'
    tags:
      - /sample
    security:
      - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            allOf:
              - $ref: 'api.yaml#/components/schemas/Sample'
            properties:
              number:
                type: string
                readOnly: false
    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, dev, admin'
    x-doc: integrity has to be ensured
    tags:
      - /sample
    responses:
      200:
        description: field names and quantity of usage
        content:
          application/json:
            schema:
              type: array
              items:
                properties:
                  name:
                    type: string
                  qty:
                    type: number
                    example: 20
      401:
        $ref: 'api.yaml#/components/responses/401'
      500:
        $ref: 'api.yaml#/components/responses/500'