# This file was automatically generated - all changes will be lost\n
openapi: 3.1.0
info:
  title: booking-backend 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/{ID}/lock:
    put:
      operationId: 'lockBooking'
      security:
        - JWT:
          - booking
          - booking:use
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
      - booking-backend
      summary: >-
        Locks the current booking so the devices can be used. 
        This sets the status to "active" This means that the booking can not be cancelled or (currently not implemented) the end time can not be set to a prior time.
        If called multiple times, the booking will be locked only once.
      responses:
        '200':
          description: All devices were booked by user.
          content:
            application/json:
              schema:
                type: array
                description: The list of booked devices and selected real devices. Order is guaranteed to be the same as in the booking.
                items:
                  type: object
                  required:
                    - Requested
                    - Selected
                  properties:
                    Requested:
                      type: string
                      format: uri
                    Selected:
                      type: string
                      format: uri
        '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
        '412':
          description: The current booking status is not correct.
        '500':
          description: >-
            Request could not be answered. An error string containing the reason
            will be returned.
          content:
            application/json:
              schema:
                type: string
                description: Error string
        '503':
          description: >-
            Service is unable to respond in time, possibly overloaded. Try again in a few minutes.
    delete:
      operationId: 'unlockBooking'
      security:
        - JWT:
          - booking
          - booking:use
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
      - booking-backend
      summary: >-
        Unlocks all devices belonging to a booking, status will be set to 'booked'.
      responses:
        '200':
          description: Unlocking was successful.
        '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
        '412':
          description: The current booking status is not correct.      
        '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.
  /booking_callback/{ID}:
    post:
      operationId: 'bookingCallback'
      security:
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/ID'
          name: ID
          schema:
            type: string
          required: true
          description: ID of Booking
      tags:
      - booking-backend
      summary: >-
        Callback used for updating device info / booking info.
      responses:
        '200':
          description: Update was processed.
        '404':
          description: Callback is no longer needed.
        '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.
