openapi: 3.0.2


info:
  title: Digital fingerprint of plastics - API
  version: 1.0.0
  description: |
    This API gives access to the project database.<br>
    Access is restricted. Authentication can be obtained with HTTP Basic Auth using username and password. Data access methods can also be accessed using an API key at the URL ending like ?key=xxx<br>
    There are a number of different user levels: <br>
    <ul>
      <li>read: read access to the samples database</li>
      <li>write: write access to the samples database, users can change only the values they created</li>
      <li>maintain: functions like changing templates, validating data, changing values of others</li>
      <li>dev: handling machine learning models</li>
      <li>admin: user administration</li>
    </ul>


servers:
  - url: http://localhost:3000
    description: local server
  - url: https://digital-fingerprint-of-plastics-api.apps.de1.bosch-iot-cloud.com/
    description: server on the BIC


security:
  - ApiKey: []
  - BasicAuth: []


tags:
  - name: /
  - name: /sample
  - name: /material
  - name: /condition
  - name: /measurement
  - name: /templates
  - name: /model
  - name: /user


paths:
  /:
    get:
      summary: Root method
      tags:
        - /
      security: []
      responses:
        200:
          description: Server is working
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: 'API server up and running!'
        500:
          $ref: '#/components/responses/500'

  /samples:
    get:
      summary: TODO all samples in overview
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /sample
      responses:
        200:
          description: samples overview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Samples'
        401:
          $ref: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'
  /sample/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      summary: TODO sample details
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /sample
      responses:
        200:
          description: samples details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleDetail'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/change sample
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /sample
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sample'
      responses:
        200:
          description: samples details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleDetail'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete sample
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /sample
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
  /sample/notes/fields:
    get:
      summary: TODO list all existing field names for custom notes fields
      description: 'levels: write, maintain, dev, admin'
      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: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'

  /material/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      summary: TODO get material details
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /material
      responses:
        200:
          description: created material
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Material'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/change material
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /material
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Material'
      responses:
        200:
          description: material details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Material'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete material
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /material
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        500:
          $ref: '#/components/responses/500'

  /condition/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      summary: TODO condition by id
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /condition
      responses:
        200:
          description: condition details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Condition'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/change condition
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /condition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Condition'
      responses:
        200:
          description: condition details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Condition'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete condition
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /condition
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'

  /measurement/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      summary: TODO measurement values by id
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /measurement
      responses:
        200:
          description: measurement details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/change measurement
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /measurement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Measurement'
      responses:
        200:
          description: measurement details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete measurement
      description: 'levels: write, maintain, dev, admin'
      tags:
        - /measurement
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'

  /template/treatments:
    get:
      summary: TODO all available treatment methods
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /templates
      security:
        - BasicAuth: []
      responses:
        200:
          description: list of treatments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Template'
                example:
                  name: heat aging
                  parameters:
                    - name: method
                      range:
                        - copper
        401:
          $ref: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'
  /templates/treatment/{name}:
    parameters:
      - $ref: '#/components/parameters/Name'
    get:
      summary: TODO treatment method details
      description: 'levels: read, write, maintain, admin'
      tags:
        - /templates
      security:
        - BasicAuth: []
      responses:
        200:
          description: treatment details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Template'
                example:
                  name: heat aging
                  parameters:
                    - name: method
                      range:
                        - copper
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/change treatment method
      description: 'levels: maintain, admin'
      tags:
        - /templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Template'
              example:
                name: heat aging
                parameters:
                  - name: method
                    range:
                      - copper
      responses:
        200:
          description: treatment details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Template'
                example:
                  name: heat aging
                  parameters:
                    - name: method
                      range:
                        - copper
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete treatment method
      description: 'levels: maintain, admin'
      tags:
        - /templates
      responses:
        200:
          $ref: '#/components/responses/200'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
  /template/measurements:
    get:
      summary: TODO all available measurement methods
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /templates
      security:
        - BasicAuth: []
      responses:
        200:
          description: list of measurement methods
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Template'
                example:
                  name: humidity
                  parameters:
                    - name: kf
                      range:
                        min: 0
                        max: 2
        401:
          $ref: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'
  /templates/measurement/{name}:
    parameters:
      - $ref: '#/components/parameters/Name'
    get:
      summary: TODO measurement method details
      description: 'levels: read, write, maintain, admin'
      tags:
        - /templates
      security:
        - BasicAuth: []
      responses:
        200:
          description: measurement details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Template'
                example:
                  name: humidity
                  parameters:
                    - name: kf
                      range:
                        min: 0
                        max: 2
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/change measurement method
      description: 'levels: maintain, admin'
      tags:
        - /templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Template'
              example:
                name: humidity
                parameters:
                  - name: kf
                    range:
                      min: 0
                      max: 2
      responses:
        200:
          description: measurement details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Template'
                example:
                  name: humidity
                  parameters:
                    - name: kf
                      range:
                        min: 0
                        max: 2
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete measurement method
      description: 'levels: maintain, admin'
      tags:
        - /templates
      responses:
        200:
          $ref: '#/components/responses/200'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'


  /model/{name}:
    parameters:
      - $ref: '#/components/parameters/Name'
    get:
      summary: TODO get model data by name
      description: 'levels: dev, admin'
      tags:
        - /model
      responses:
        200:
          description: binary model data
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO add/replace model data by name
      description: 'levels: dev, admin'
      tags:
        - /model
      requestBody:
        required: true
        description: binary model data
        content:
          application/json:
            schema:
              type: string
              format: binary
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete model data
      description: 'levels: dev, admin'
      tags:
        - /model
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'

  /users:
    get:
      summary: TODO lists all users
      description: 'levels: admin'
      tags:
        - /user
      security:
        - BasicAuth: []
      responses:
        200:
          description: user API key
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        500:
          $ref: '#/components/responses/500'
  /user/{name}:
    parameters:
      - $ref: '#/components/parameters/Name'
    get:
      summary: TODO list user details
      description: 'levels: read, write, maintain, dev get their own information without a name property specified, level: admin can get any user using the name parameter'
      tags:
        - /user
      security:
        - BasicAuth: []
      responses:
        200:
          description: user details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    put:
      summary: TODO change user details
      description: 'levels: read, write, maintain, dev can change their own information (except level) without a name property specified, level: admin can change any user using the name parameter'
      tags:
        - /user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        200:
          description: user details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
    delete:
      summary: TODO delete user
      description: 'levels: read, write, maintain, dev can delete their own account, level: admin can delete any user using the name parameter'
      tags:
        - /user
      responses:
        200:
          $ref: '#/components/responses/Ok'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
  /user/key:
    get:
      summary: TODO get API key for the user
      description: 'levels: read, write, maintain, dev, admin'
      tags:
        - /user
      security:
        - BasicAuth: []
      responses:
        200:
          description: user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        401:
          $ref: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'
  /user/new:
    post:
      summary: TODO add new user
      description: 'levels: admin'
      tags:
        - /user
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        200:
          description: user details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        500:
          $ref: '#/components/responses/500'
  /user/passreset:
    post:
      summary: TODO reset password and send mail to restore
      tags:
        - /user
      security: []
      requestBody:
        required: true
        description: mail saved in user profile to provide authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Email'
      responses:
        200:
          $ref: '#/components/responses/Ok'
        401:
          $ref: '#/components/responses/401'
        500:
          $ref: '#/components/responses/500'

components:
  schemas:
    Id:
      type: string
    _Id:
      properties:
        _id:
          allOf:
            - $ref: '#/components/schemas/Id'
          readOnly: true
    Color:
      properties:
        color:
          type: string
    SampleProperties:
      properties:
        sample_number:
          type: string
        type:
          type: string
        batch:
          type: string
        validated:
          type: boolean

    Samples:
      allOf:
        - $ref: '#/components/schemas/_Id'
        - $ref: '#/components/schemas/Color'
        - $ref: '#/components/schemas/SampleProperties'
      properties:
        material_id:
          $ref: '#/components/schemas/Id'
        note_id:
          $ref: '#/components/schemas/Id'
        user_id:
          $ref: '#/components/schemas/Id'
    Sample:
      allOf:
        - $ref: '#/components/schemas/_Id'
        - $ref: '#/components/schemas/Color'
        - $ref: '#/components/schemas/SampleProperties'
      properties:
        material:
          $ref: '#/components/schemas/Material'
        notes:
          type: object
          properties:
            comments:
              type: string
            sample_references:
              type: array
              items:
                $ref: '#/components/schemas/Id'
    SampleDetail:
      allOf:
        - $ref: '#/components/schemas/_Id'
        - $ref: '#/components/schemas/Color'
        - $ref: '#/components/schemas/SampleProperties'
      properties:
        material:
          $ref: '#/components/schemas/Material'
        notes:
          type: object
          properties:
            comments:
              type: string
            sample_references:
              type: array
              items:
                $ref: '#/components/schemas/Id'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'

    Material:
      allOf:
        - $ref: '#/components/schemas/_Id'
      properties:
        material_numbers:
          type: array
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/Color'
            properties:
              number:
                type: number
        material_group:
          type: string
        supplier:
          type: string
        material_name:
          type: string
        mineral:
          type: number
        glass_fiber:
          type: number
        carbon_fiber:
          type: number

    Condition:
      allOf:
        - $ref: '#/components/schemas/_Id'
      properties:
        sample_id:
          $ref: '#/components/schemas/Id'
        parameters:
          type: object
        treatment_template:
          $ref: '#/components/schemas/Id'

    Measurement:
      allOf:
        - $ref: '#/components/schemas/_Id'
      properties:
        condition_id:
          $ref: '#/components/schemas/Id'
        values:
          type: object
        measurement_template:
          $ref: '#/components/schemas/Id'

    Template:
      allOf:
        - $ref: '#/components/schemas/_Id'
      properties:
        name:
          type: string
        parameters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              range:
                type: object

    Email:
      required:
        - email
      properties:
        email:
          type: string
          example: john.doe@bosch.com
    User:
      allOf:
        - $ref: '#/components/schemas/_Id'
        - $ref: '#/components/schemas/Email'
      properties:
        name:
          type: string
          example: johndoe
        levels:
          type: array
          items:
            type: string
            example: read
        location:
          type: string
          example: Rng
        device_name:
          type: string
          example: Alpha II


  responses:
    400:
      description: Bad request
      content:
        application/json:
          schema:
            properties:
              status:
                type: string
                example: 'Bad request'
    401:
      description: Unauthorized
      content:
        application/json:
          schema:
            properties:
              status:
                type: string
                example: 'Unauthorized'
    403:
      description: Forbidden
      content:
        application/json:
          schema:
            properties:
              status:
                type: string
                example: 'Forbidden'
    404:
      description: Not found
      content:
        application/json:
          schema:
            properties:
              status:
                type: string
                example: 'Not found'
    500:
      description: Internal server error
      content:
        application/json:
          schema:
            properties:
              status:
                type: string
                example: 'Internal server error'
    Ok:
      description: request executed successfully
      content:
        application/json:
          schema:
            properties:
              status:
                type: string
                example: OK

  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
    Name:
      name: name
      in: path
      required: true
      schema:
        type: string

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKey:
      type: apiKey
      in: query
      name: key