# This file was automatically generated by documentation-and-generation.fish - all changes will be lost\n
openapi: 3.1.0
info:
  title: booking-frontend single api
  description: >-
    workaround for openapi-codegen, who assumes a structure where every service has its own file.
  version: 1.0.0
  x-service-name: Booking Service
servers:
  - url: /v1
tags:
  - name: schedule-service
  - name: booking-frontend
  - name: booking-backend
  - name: device-reservation

paths:
  /booking:
    post:
      operationId: 'newBooking'
      security:
        - JWT:
          - booking
          - booking:use
      tags:
        - booking-frontend
      summary: Books an experiment.
      x-optional-url: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
               - Devices
               - Time
              properties:
                Devices:
                  type: array
                  description: List of devices which should be added.
                  items:
                    $ref: '#/components/schemas/Device'
                Time:
                  $ref: '#/components/schemas/Timeslot'
                Type:
                  description: Type of booking. Currently, only one type is defined, but others might follow (e.g. priority booking). If empty, 'normal' is assumed.
                  type: string
                  enum:
                   - normal
      responses:
        '200':
          description: The booking was accepted. The booking status will display whether the booking of all devices was successful.
          content:
            application/json:
              schema:
                type: object
                required:
                 - BookingID
                properties:
                  BookingID:
                    type: string
                    format: uri
                    description: ID at which the booking can be managed.
        '401':
          description: No authorisation header found.
        '403':
          description: >-
            Caller is not allowed to call this method. Usually, caller is missing required scopes.
        '500':
          description: >-
            Request could not be answered. An error string containing the reason
            will be returned.
          content:
            application/json:
              schema:
                description: Error description
                type: string
        '503':
          description: >-
            Service is unable to respond in time, possibly overloaded. Try again in a few minutes.
  /booking/{ID}:
    patch:
      operationId: 'updateBooking'
      security:
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
        - booking-frontend
      summary: >
        Allows the addition of devices to a booking (removing of devices is not supportet) or the registration of callbacks.
        For adding devices, the scope 'booking:use' is required.
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              -  type: object
                 description: Use this request for adding devices.
                 properties:
                    Locked:
                      type: boolean
                      description: Expresses whether the devices should be locked. Must match current status of booking. Is assumed to be false if not set.
                    Devices:
                     type: array
                     description: List of devices which should be added.
                     items:
                      $ref: '#/components/schemas/Device'
              - type: object
                description: Use this request for adding callbacks.
                properties:
                  Callback:
                    type: string
                    format: uri
                    description: Callback which should be called at changes.
        required: true
      responses:
        '200':
          description: The booking change was accepted. The booking status will display whether the booking of all devices was successful.
          content:
            application/json:
              schema:
                type: object
                required:
                  - BookingID
                properties:
                  BookingID:
                    type: string
                    format: uri
        '400':
          description: >-
            The request was not build correctly (e.g. both Devices and Callback are requested).
            See error returned for more details
          content:
            application/json:
              schema:
                type: string
                description: Error description
        '401':
          description: No authorisation header found.
        '403':
          description: >-
            Caller is not allowed to call this method. Usually, caller is missing required scopes.
        '404':
          description: Request contains unknown booking ID.
        '423':
          description: >-
            The booking 'locked' status and the requested locked status do not match.
        '500':
          description: >-
            Request could not be answered. An error string containing the reason
            will be returned.
          content:
            application/json:
              schema:
                type: string
                description: Error description
        '503':
          description: >-
            Service is unable to respond in time, possibly overloaded. Try again in a few minutes.
    delete:
      operationId: 'deleteBooking'
      security:
        - JWT:
          - booking
          - booking:use
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
        - booking-frontend
      summary: Cancels a booking, as long as the booking was originally done by you.
      responses:
        '200':
          description: >-
            The booking was cancelled. All associated devices were released.
        '401':
          description: No authorisation header found.
        '403':
          description: >-
            Caller is not allowed to call this method. Usually, caller is missing required scopes.
        '404':
          description: Request contains unknown booking ID.
        '423':
          description: >-
            The booking is currently locked, deletion not possible.
        '500':
          description: >-
            Request could not be answered. An error string containing the reason
            will be returned.
          content:
            application/json:
              schema:
                type: string
                description: Error description
        '503':
          description: >-
            Service is unable to respond in time, possibly overloaded. Try again in a few minutes.
    get:
      operationId: 'getBooking'
      security:
        - JWT:
          - booking
          - booking:use
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
      - booking-frontend
      summary: >-
        Returns whether a list of devices is currently booked for a user.
      responses:
        '200':
          description: Returns the current booking.
          content:
            application/json:
              schema:
                type: object
                required:
                 - Booking
                 - Locked
                properties:
                  Booking:
                    $ref: '#/components/schemas/Booking'
                  Locked:
                    type: boolean
                    description: Shows if the booking is in a locked status.
        '401':
          description: No authorisation header found.
        '403':
          description: >-
            Caller is not allowed to call this method. Usually, caller is missing required scopes.
        '404':
          description: Request contains unknown ID
        '500':
          description: >-
            Request could not be answered. An error string containing the reason
            will be returned.
          content:
            application/json:
              schema:
                type: string
                description: Error code
        '503':
          description: >-
            Service is unable to respond in time, possibly overloaded. Try again in a few minutes.
  /booking/{ID}/destroy:
    delete:
      operationId: 'destroyBooking'
      security:
        - JWT:
          - booking
          - booking:destroy
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
        - booking-frontend
      summary: Allows selected persons (like lab manager) to remove a user booking. To avoid mistakes, this is a different path than normal delete.
      responses:
        '200':
          description: >-
            The booking was cancelled. All associated devices were released.
        '401':
          description: No authorisation header found.
        '403':
          description: >-
            Caller is not allowed to call this method. Usually, caller is missing required scopes.
        '404':
          description: Request contains unknown booking ID.
        '423':
          description: >-
            The booking is currently locked, deletion not possible.
        '500':
          description: >-
            Request could not be answered. An error string containing the reason
            will be returned.
          content:
            application/json:
              schema:
                type: string
                description: Error description
        '503':
          description: >-
            Service is unable to respond in time, possibly overloaded. Try again in a few minutes.
components:
  parameters:
    ID:
      in: path
      name: ID
      description: String ID without any specified strcture. Only needed because the validator at the time of writing can not handle inline validation (e.g. ensure that a string extracted from a path is a string).
      schema:
        type: string
      required: true
  schemas:
    Booking:
      title: Booking
      description: A booking in the booking system.
      type: object
      required:
        - ID
        - Time
        - Devices
        - Status
        - You
        - External
      properties:
        ID:
          type: string
          format: uri
          description: Unique ID of the booking.
        Time:
          $ref: '#/components/schemas/Timeslot'
        Devices:
          type: array
          items:
            type: string
            format: uri
        Type:
          description: Type of booking. Currently, only one type is defined, but others might follow (e.g. priority booking). If empty, 'normal' is assumed.
          type: string
          enum:
            - normal
        Status:
          description: >
            Current status of the booking. While the booking is pending, it can not be used.
            Will change automatically and can not be set by user. 'rejected' is set when the initial booking failed,
            'cancelled' when the booking was deleted / cancelled after it was once active.
            The 'active-*' will be used when a device was added after the booking was locked.
          type: string
          enum:
            - pending
            - booked
            - rejected
            - cancelled
            - active
            - active-pending
            - active-rejected
        You:
          type: boolean
          description: If true, this booking was done by you.
        External:
          type: boolean
          description: Shows whether the booking was done by an external institution.
        Message:
          type: string
          description: User readable notes about the status of the booking (e.g. if devices are unknown).
    Device:
      title: Device
      description: A device might either be a physical/virtual device or a group of device.
      type: object
      required:
        - ID
      properties:
        ID:
          type: string
          description: Unique ID of the device. Contains the institution (by having an end point at that institution)
          format: uri
    Experiment:
      title: Experiment
      description: An experiment describes a set of devices and how they should be connected (potentially among other metadata).
      type: object
      required:
        - Devices
      properties:
        Devices:
          type: array
          description: List of devices used in experiment.
          items:
            $ref: '#/components/schemas/Device'
        Description:
          type: string
          description: >
            User provided description, for example might be a reason for the booking (e.g. maintenance)
            or a link to the experiment. Might be empty or missing.
    Timeslot:
      title: Timeslot
      description: A time slot represents a slice of time used for bookings.
      type: object
      required:
        - Start
        - End
      properties:
        Start:
          type: string
          description: Start time of the booking.
          format: date-time
        End:
          type: string
          description: End time of the booking.
          format: date-time
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        As this is the API description of the internal Device API, the only supported security schema is the JWT bearer token.
        This token will be populated by the API Gateway.
        To learn about the general Authentification scheme, please refer to the [Authentication section](https://cross-lab-project.github.io/crosslab/backend.html#authentification) in the CrossLab architecture description.
