definma-api/api/sample.yaml

/samples:
  get:
    summary: all samples in overview
    description: 'Auth: all, levels: read, write, maintain, dev, 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|all, defaults to validated'
        in: query
        schema:
          type: string
        example: all
      - 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: csv
        description: output as csv
        in: query
        schema:
          type: boolean
        example: false
      - 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', field: 'material.m', values: ['15']} using encodeURIComponent(JSON.stringify({}))"
        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"]
    responses:
      200:
        description: samples overview (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 page is specified
            schema:
              type: integer
              example: 243
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'api.yaml#/components/schemas/SampleRefs'
      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: maintain, 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, maintain, 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, maintain, dev, admin<br>Returns validated as well as new measurements'
    x-doc: deleted samples are available only for maintain/admin
    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, 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, 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/restore/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  put:
    summary: restore sample
    description: 'Auth: basic, levels: maintain, 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: maintain, 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, maintain, 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, maintain, 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'