openapi-spec.yaml

swagger: '2.0'
info:
  description: Running with /api base path
  version: 0.1.0
  title: Jiskefet
basePath: /api
tags:
  - name: logs
    description: ''
  - name: runs
    description: ''
schemes:
  - http
securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header
paths:
  /runs:
    post:
      summary: Creates a Run.
      parameters:
        - name: CreateRunDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/CreateRunDto'
      responses:
        '200':
          description: Succesfully created a Run.
          schema:
            type: object
        '409':
          description: There already exist a Run with this Run number.
      tags:
        - runs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
    get:
      summary: Returns all Runs.
      parameters:
        - type: string
          name: orderBy
          required: false
          in: query
          description: On which field to order on.
        - type: string
          name: orderDirection
          required: false
          in: query
          description: 'The order direction, either ascending or descending.'
          enum:
            - ASC
            - DESC
        - type: integer
          format: int64
          name: pageSize
          required: false
          in: query
          description: The maximum amount of logs in each result.
          default: '25'
        - type: integer
          format: int64
          name: pageNumber
          required: false
          in: query
          description: 'The current page, i.e. the offset in the result set based on pageSize.'
          default: '1'
        - type: integer
          format: int64
          name: runNumber
          required: false
          in: query
          description: The id of the log.
        - type: string
          name: startTimeO2Start
          required: false
          in: query
          description: The lower bound of the timeO2Start filter range.
          format: date-time
        - type: string
          name: endTimeO2Start
          required: false
          in: query
          description: The upper bound of the timeO2Start filter range.
          format: date-time
        - type: string
          name: startTimeTrgStart
          required: false
          in: query
          description: The lower bound of the timeTrgStart filter range.
          format: date-time
        - type: string
          name: endTimeTrgStart
          required: false
          in: query
          description: The upper bound of the timeTrgStart filter range.
          format: date-time
        - type: string
          name: startTimeTrgEnd
          required: false
          in: query
          description: The lower bound of the timeTrgEnd filter range.
          format: date-time
        - type: string
          name: endTimeTrgEnd
          required: false
          in: query
          description: The upper bound of the timeTrgEnd filter range.
          format: date-time
        - type: string
          name: startTimeO2End
          required: false
          in: query
          description: The lower bound of the timeO2End filter range.
          format: date-time
        - type: string
          name: endTimeO2End
          required: false
          in: query
          description: The upper bound of the timeO2End filter range.
          format: date-time
        - type: string
          name: activityId
          required: false
          in: query
          description: The id of the activity.
        - type: string
          name: runType
          required: false
          in: query
          description: The type of the run.
        - type: string
          name: runQuality
          required: false
          in: query
          description: The quality of the run.
      responses:
        '200':
          description: Succesfully returned Runs.
          schema:
            type: object
        '204':
          description: There are no Runs.
      tags:
        - runs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/runs/{id}':
    get:
      summary: Returns a specific Run.
      parameters:
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returned a specific Run.
        '204':
          description: There is no Run with the give Run number.
      tags:
        - runs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
    patch:
      summary: Updates certain fields of a Run.
      parameters:
        - name: PatchRunDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/PatchRunDto'
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully updated a Run.
      tags:
        - runs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/runs/{id}/logs':
    patch:
      summary: Links a Log to a specific Run.
      parameters:
        - name: LinkLogToRunDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/LinkLogToRunDto'
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully linked a Log to a Run.
      tags:
        - runs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  /logs:
    post:
      summary: Creates a Log.
      parameters:
        - name: CreateLogDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/CreateLogDto'
      responses:
        '200':
          description: Succesfully created a Log
          schema:
            $ref: '#/definitions/Log'
      tags:
        - logs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
    get:
      summary: Returns all Logs.
      parameters:
        - type: string
          name: orderBy
          required: false
          in: query
          description: On which field to order on.
        - type: string
          name: orderDirection
          required: false
          in: query
          description: 'The order direction, either ascending or descending.'
          enum:
            - ASC
            - DESC
        - type: integer
          format: int64
          name: pageSize
          required: false
          in: query
          description: The maximum amount of logs in each result.
          default: '25'
        - type: integer
          format: int64
          name: pageNumber
          required: false
          in: query
          description: 'The current page, i.e. the offset in the result set based on pageSize.'
          default: '1'
        - type: integer
          format: int64
          name: logId
          required: false
          in: query
          description: The id of the log.
        - type: string
          name: searchterm
          required: false
          in: query
          description: Search for a term that exists in the title field of a log.
        - type: string
          name: subtype
          required: false
          in: query
          description: The subtype of the log.
          enum:
            - run
            - subsystem
            - announcement
            - intervention
            - comment
        - type: string
          name: origin
          required: false
          in: query
          description: The origin/creator of the log.
          enum:
            - human
            - process
        - type: string
          name: startCreationTime
          required: false
          in: query
          description: The lower bound of the creation time filter range.
        - type: string
          name: endCreationTime
          required: false
          in: query
          description: The upper bound of the creation time filter range.
        - type: integer
          format: int64
          name: user
          required: false
          in: query
          description: The author of the log..
      responses:
        '200':
          description: Succesfully returns Logs.
      tags:
        - logs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/logs/{id}':
    get:
      summary: Returns a specific Log.
      parameters:
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returns a specific Log.
      tags:
        - logs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/logs/{id}/runs':
    patch:
      summary: Links a Run to a specific Log.
      parameters:
        - name: LinkRunToLogDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/LinkRunToLogDto'
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully linked a Run to a Log.
      tags:
        - logs
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/flp/{name}/runs/{id}':
    get:
      summary: Returns a specific FLP based on RunId.
      parameters:
        - type: string
          name: name
          required: true
          in: path
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returned a FLP.
      tags:
        - flp
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
    patch:
      summary: Updates a FLP based on a RunId and FLPName.
      parameters:
        - name: PatchFlpDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/PatchFlpDto'
        - type: string
          name: name
          required: true
          in: path
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully updated a FLP.
      tags:
        - flp
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  /flp:
    post:
      summary: Creates a FLP.
      parameters:
        - name: CreateFlpDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/CreateFlpDto'
      responses:
        '200':
          description: Succesfully created a FLP.
      tags:
        - flp
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  /attachments:
    post:
      summary: Creates a Attachment.
      parameters:
        - name: CreateAttachmentDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/CreateAttachmentDto'
      responses:
        '200':
          description: Succesfully created a Attachment.
      tags:
        - attachments
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/attachments/{id}/logs':
    get:
      summary: Returns Attachments that belong to a specific Log.
      parameters:
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returned the Attachments.
      tags:
        - attachments
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  /subsystems:
    get:
      summary: Returns all Subsystems.
      responses:
        '200':
          description: Succesfully returned Subsystems.
      tags:
        - subsystems
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/subsystems/{id}':
    get:
      summary: Returns a specific Subsystem.
      parameters:
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returned a specific Subsystem.
      tags:
        - subsystems
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/users/{id}':
    get:
      parameters:
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: ''
      tags:
        - users
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/users/{id}/tokens':
    get:
      summary: Returns all generated Tokens for a specific User.
      parameters:
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returned Tokens.
      tags:
        - users
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
    post:
      summary: Creates a Token and links it to a Subsytem.
      parameters:
        - name: CreateSubSystemPermissionDto
          required: true
          in: body
          schema:
            $ref: '#/definitions/CreateSubSystemPermissionDto'
        - name: id
          type: integer
          format: int64
          required: true
          in: path
      responses:
        '200':
          description: Succesfully created a Token.
      tags:
        - users
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  '/users/{id}/logs':
    get:
      summary: Returns all Logs for a specific User.
      parameters:
        - type: string
          name: orderBy
          required: false
          in: query
          description: On which field to order on.
        - type: string
          name: orderDirection
          required: false
          in: query
          description: 'The order direction, either ascending or descending.'
          enum:
            - ASC
            - DESC
        - type: string
          name: pageSize
          required: false
          in: query
          description: The maximum amount of logs in each result.
          default: '25'
        - type: string
          name: pageNumber
          required: false
          in: query
          description: 'The current page, i.e. the offset in the result set based on pageSize.'
          default: '1'
        - type: string
          name: logId
          required: false
          in: query
          description: The id of the log.
        - type: string
          name: searchterm
          required: false
          in: query
          description: Search for a term that exists in the title field of a log.
        - type: string
          name: subtype
          required: false
          in: query
          description: The subtype of the log.
          enum:
            - run
            - subsystem
            - announcement
            - intervention
            - comment
        - type: string
          name: origin
          required: false
          in: query
          description: The origin/creator of the log.
          enum:
            - human
            - process
        - type: string
          name: startCreationTime
          required: false
          in: query
          description: The lower bound of the creation time filter range.
        - type: string
          name: endCreationTime
          required: false
          in: query
          description: The upper bound of the creation time filter range.
        - type: string
          name: user
          required: false
          in: query
          description: The author of the log..
        - type: integer
          format: int64
          name: id
          required: true
          in: path
      responses:
        '200':
          description: Succesfully returened Logs.
      tags:
        - users
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  /auth:
    get:
      summary: Authenticate a user by giving an Authorization Grant.
      parameters:
        - name: grant
          required: true
          in: query
          type: string
      responses:
        '200':
          description: User has successfully authenticated and a JWT has been given as a response.
        '401':
          description: User is unauthorized due to an invalid Authorization Grant.
        '422':
          description: User has not provided an Authorization Grant as a query parameter.
      tags:
        - authentication
      produces:
        - application/json
      consumes:
        - application/json
  /user/profile:
    get:
      summary: Returns the user's profile
      parameters: []
      responses:
        '200':
          description: User successfully received profile information.
        '400':
          description: No JWT could be found in headers.
        '401':
          description: User is unauthorized
      tags:
        - authentication
      produces:
        - application/json
      consumes:
        - application/json
  /test-token:
    get:
      summary: Returns a JWT for authorization when running end-to-end tests.
      parameters:
        - name: hashedSecret
          required: false
          in: query
          type: string
      responses:
        '200':
          description: The hashed secret given matches the secret in the environment and a JWT is returned.
        '400':
          description: The required query parameter 'hashedSecret' is missing.
        '401':
          description: Hashed secret was not accepted
      tags:
        - authentication
      produces:
        - application/json
      consumes:
        - application/json
  /overview:
    get:
      summary: Returns all Overviews that belong to a specific Log.
      parameters:
        - type: string
          name: timeRange
          required: false
          in: query
          description: In which time range the logs of eachsubsystem should be posted
      responses:
        '200':
          description: Succesfully returned Overviews.
      tags:
        - overview
      security:
        - bearer: []
      produces:
        - application/json
      consumes:
        - application/json
  /setting:
    get:
      summary: Returns settings.
      responses:
        '200':
          description: Succesfully returns setting.
      tags:
        - setting
      produces:
        - application/json
      consumes:
        - application/json
definitions:
  CreateRunDto:
    type: object
    properties:
      runNumber:
        type: integer
        format: int64
        example: 1
        description: The id of the run
      O2StartTime:
        type: string
        example: '2019-01-11T15:07:52.340Z'
        description: Current Date
        format: date-time
      TrgStartTime:
        type: string
        example: '2019-01-11T15:07:52.340Z'
        description: Current Date
        format: date-time
      runType:
        type: string
        example:
          - COSMICS
        description: What kind of run.
        enum:
          - PHYSICS
          - COSMICS
          - TECHNICAL
      activityId:
        type: string
        example: Sl4e12ofb83no92ns
        description: The id of the activity.
      nDetectors:
        type: integer
        format: int64
        example: 16
        description: Number of detectors during run.
      nFlps:
        type: integer
        format: int64
        example: 7
        description: Number of FLPs that computed data
      nEpns:
        type: integer
        format: int64
        example: 8
        description: Number of EPNs that stored data
    required:
      - runNumber
      - O2StartTime
      - TrgStartTime
      - runType
      - activityId
      - nDetectors
      - nFlps
      - nEpns
  Log:
    type: object
    properties:
      logId:
        type: integer
        format: int64
      origin:
        type: string
      creationTime:
        type: string
        format: date-time
      title:
        type: string
      body:
        type: string
      subsystemFkSubsystemId:
        type: integer
        format: int64
      announcementValidUntil:
        type: string
        format: date-time
      commentFkParentLogId:
        type: integer
        format: int64
      commentFkRootLogId:
        type: integer
        format: int64
      runs:
        type: array
        items:
          type: string
    required:
      - logId
      - origin
      - creationTime
      - title
      - body
      - runs
  FlpRole:
    type: object
    properties:
      run:
        type: object
    required:
      - run
  Run:
    type: object
    properties:
      runNumber:
        type: integer
        format: int64
      O2StartTime:
        type: string
        format: date-time
      TrgStartTime:
        type: string
        format: date-time
      TrgEndTime:
        type: string
        format: date-time
      O2EndTime:
        type: string
        format: date-time
      activityId:
        type: string
      runType:
        type: array
        items:
          type: string
      runQuality:
        type: array
        items:
          type: string
      nDetectors:
        type: integer
        format: int64
      nFlps:
        type: integer
        format: int64
      nEpns:
        type: integer
        format: int64
      nTimeframes:
        type: integer
        format: int64
      nSubtimeframes:
        type: integer
        format: int64
      bytesReadOut:
        type: integer
        format: int64
      bytesTimeframeBuilder:
        type: integer
        format: int64
      logs:
        type: array
        minProperties: 1
        items:
          $ref: '#/definitions/Log'
      flpRoles:
        type: array
        items:
          $ref: '#/definitions/FlpRole'
    required:
      - runNumber
      - O2StartTime
      - TrgStartTime
      - activityId
      - runType
      - nDetectors
      - nFlps
      - nEpns
      - logs
      - flpRoles
  LinkLogToRunDto:
    type: object
    properties:
      logId:
        type: integer
        format: int64
        example: '1'
        description: The id of the log to link to the run.
    required:
      - logId
  PatchRunDto:
    type: object
    properties:
      TrgEndTime:
        type: string
        format: date-time
        example: '2019-01-11T15:07:52.513Z'
        description: Current Date at end of run
      O2EndTime:
        type: string
        format: date-time
        example: '2019-01-11T15:07:52.514Z'
        description: Current Date at end of run
      runQuality:
        type: string
        example:
          - Good
        description: The quality of the run.
        enum:
          - Good
          - Bad
          - Unknown
    required:
      - TrgEndTime
      - O2EndTime
      - runQuality
  CreateLogDto:
    type: object
    properties:
      subtype:
        type: string
        example: run
        description: What kind of log is it?
        enum:
          - run
          - subsystem
          - announcement
          - intervention
          - comment
      origin:
        type: string
        example: human
        description: Where did the log come from?
        enum:
          - human
          - process
      title:
        type: string
        example: log for run 12
        description: describes the log in short
      body:
        type: string
        example: lorum ipsum
        description: describes the log in depth
      attachments:
        type: array
        example: []
        description: Attachments of this log
        items:
          type: string
      runs:
        type: array
        example:
          - 1
        description: Attached run numbers of this log
        items:
          type: string
      user:
        type: integer
        format: int64
        example: '1'
        description: Author of log
    required:
      - subtype
      - origin
      - title
      - body
      - attachments
      - runs
      - user
  LinkRunToLogDto:
    type: object
    properties:
      runNumber:
        type: integer
        format: int64
        example: '1'
        description: The id of the run to link to the log.
    required:
      - runNumber
  CreateFlpDto:
    type: object
    properties:
      flpName:
        type: string
        example: FLP-TPC-1
        description: Name of the flp
      flpHostname:
        type: string
        example: someserver.cern.ch
        description: 'Name of the hostmachine, where the flp comes from.'
      run:
        type: integer
        format: int64
        example: 1
        description: Attached run numbers of this log
    required:
      - flpName
      - flpHostname
      - run
  PatchFlpDto:
    type: object
    properties:
      nSubTimeframes:
        type: integer
        format: int64
        example: 50
        description: Number of subtimeframes processed in this FLP. Updated regularly.
      equipmentBytes:
        type: integer
        format: int64
        example: 50
        description: data volume out from the readout 'equipment' component in bytes. Can reach PetaBytes.Updated regularly.
      recordingBytes:
        type: integer
        format: int64
        example: 50
        description: data volume out from the readout 'recording' component in bytes. Can reach PetaBytes. Updated regularly.
      fairMQBytes:
        type: integer
        format: int64
        example: 50
        description: data volume out from the readout 'fmq' component in bytes. Can reach PetaBytes. Updated regularly.
    required:
      - nSubTimeframes
      - equipmentBytes
      - recordingBytes
      - fairMQBytes
  CreateAttachmentDto:
    type: object
    properties:
      title:
        type: string
        example: This is a very important file.
        description: What is the name of the file?
      fileName:
        type: string
        example: VeryImportantDocument.txt
        description: Name of the uploaded file.
      fileSize:
        type: integer
        format: int64
        example: 42
        description: File size in bytes.
      fileMime:
        type: string
        example: text/plain
        description: What kind of file is it?
      contentType:
        type: string
        example: 'content-type: text/plain'
        description: Content type header containing file mime
      fileData:
        type: string
        example: VmVyeSBpbXBvcnRhbnQK
        description: The base64 encoded file data.
      logId:
        type: integer
        format: int64
        example: 1
        description: The id of the corresponding Log
    required:
      - title
      - fileName
      - fileSize
      - fileMime
      - contentType
      - fileData
      - logId
  User:
    type: object
    properties: {}
  SubSystem:
    type: object
    properties: {}
  CreateSubSystemPermissionDto:
    type: object
    properties:
      user:
        title: User
        allOf:
          - $ref: '#/definitions/User'
          - example: 8
            description: Id of the user.
      subsystem:
        title: SubSystem
        allOf:
          - $ref: '#/definitions/SubSystem'
          - example: 8
            description: Id of the subsystem.
      isMember:
        type: boolean
        example: true
        description: If the user is a member.
      editEorReason:
        type: boolean
        example: true
        description: Reason for the end of run.
      subSystemHash:
        type: string
        example: 0f62642f-a46c-4c3a-925f-5070d8b0594e
        description: A unique token for a subsystem linked to a user.
      subSystemTokenDescription:
        type: string
        example: Read and Write token for subsystem
        description: A description for the subsystem.
    required:
      - user
      - subsystem
      - isMember
      - editEorReason
      - subSystemHash
      - subSystemTokenDescription