Archived
2
This repository has been archived on 2023-03-02. You can view files and clone it, but cannot push or open issues or pull requests.
definma-api/api/sample.yaml

354 lines
10 KiB
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({}))"
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: csv
description: output as csv, only available for dev and admin
in: query
schema:
type: boolean
example: false
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'