api.swagger.yaml

openapi: 3.0.0
info:
  title: Gateway
  version: '1.0'
  description: 'The gateway of the UEMS platform, used by the frontend web API'
  contact:
    name: St Andrews Students Association Ents Crew
    email: convenor@entscrew.net
    url: 'https://entscrew.net'
servers:
  - url: 'http://localhost:3000'
paths:
  /ents:
    get:
      summary: Retrieve ents states
      tags:
        - ents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EntStateRepresentation'
              examples: {}
      operationId: get-ents
      description: Retrieves all valid ents states currently loaded on the system
      parameters:
        - schema:
            type: string
          in: query
          name: name
          description: The name or a substring of the name to search with
        - schema:
            type: string
          in: query
          name: icon
          description: The exact icon to search with
        - schema:
            type: string
            pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
          in: query
          name: color
          description: 'A 7 character hex colour code, this has to variance'
        - schema:
            type: string
          in: query
          name: id
          description: 'The unique ent ID if fetching one result. Use /ent/:id if you know the result exists'
    post:
      summary: Creates a new ent state
      operationId: post-ents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Inserts a new ent state into the system
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                icon:
                  type: string
                color:
                  type: string
                  pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
              required:
                - name
                - icon
                - color
      tags:
        - ents
  '/ents/{entID}':
    parameters:
      - schema:
          type: string
        name: entID
        in: path
        required: true
        description: The unique identifier for the ent state
    get:
      summary: Retrieves a single ent state
      tags:
        - ents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/EntStateRepresentation'
      operationId: get-ents-entID
      description: Fetches a single valid ent state
      parameters: []
    delete:
      summary: Removes an ent state
      operationId: delete-ents-entID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Removes the ent state identified by this ID
      tags:
        - ents
    patch:
      summary: Updates properties of an ent state
      operationId: patch-ents-entID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Updates properties of an ent state
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                icon:
                  type: string
                color:
                  type: string
                  pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
      tags:
        - ents
  /equipment:
    get:
      summary: Fetches all equipment entries
      tags:
        - equipment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EquipmentRepresentation'
      operationId: get-equipment
      description: Retrieves all pieces of equipment registered on the system with their populated attributes
      parameters:
        - schema:
            type: string
          in: query
          name: id
          description: 'the unique id of the equipment if fetching one result. Also use /equipment/:id'
        - schema:
            type: string
          in: query
          name: assetID
          description: 'The asset identifier to search with, this must be an exact match'
        - schema:
            type: string
          in: query
          name: name
          description: The name or a substring of it to search with
        - schema:
            type: string
          in: query
          name: manufacturer
          description: The manufacturer to search with
        - schema:
            type: string
          in: query
          name: model
          description: The desired model of the equipment
        - schema:
            type: string
          in: query
          name: miscIdentifier
          description: Searches by the misc identifier associated with the equipment
        - schema:
            type: number
          in: query
          name: amount
          description: 'The amount of equipment required in the results, this has no leniency'
        - schema:
            type: string
          in: query
          name: locationID
          description: The system ID for the venue in which this equipment is placed
        - schema:
            type: string
          in: query
          name: locationSpecifier
          description: The specification of where in the venue the equipment is located. This must be an exact match
        - schema:
            type: string
          in: query
          name: managerID
          description: The system user id of the user who manages this piece of equipment
        - schema:
            type: number
          in: query
          name: date
          description: The data at which this equipment was created
        - schema:
            type: string
          in: query
          name: category
          description: 'The category of this equipment, must be an exact match'
    post:
      summary: Inserts a new piece of equipment
      operationId: post-equipment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EquipmentRepresentation'
      description: Create a new piece of equipment in the system
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                manufacturer:
                  type: string
                model:
                  type: string
                amount:
                  type: number
                locationID:
                  type: string
                category:
                  type: string
                assetID:
                  type: string
                miscIdentifier:
                  type: string
                locationSpecifier:
                  type: string
              required:
                - name
                - manufacturer
                - model
                - amount
                - locationID
                - category
      tags:
        - equipment
  '/equipment/{equipmentID}':
    parameters:
      - schema:
          type: string
        name: equipmentID
        in: path
        required: true
        description: The unique equipment entry
    get:
      summary: Retrieves a single equipment element
      tags:
        - equipment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/EquipmentRepresentation'
      operationId: get-equipment-equipmentID
      description: Fetches a single equipment element
    delete:
      summary: Deletes an existing equipment entry
      operationId: delete-equipment-equipmentID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Removes the equipment associated with this ID
      tags:
        - equipment
    patch:
      summary: Update properties of a piece of equipment
      operationId: patch-equipment-equipmentID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                assetID:
                  type: string
                name:
                  type: string
                manufacturer:
                  type: string
                model:
                  type: string
                miscIdentifier:
                  type: string
                amount:
                  type: number
                locationID:
                  type: string
                locationSpecifier:
                  type: string
                managerID:
                  type: string
                category:
                  type: string
      description: Updates properties on a piece of equipment
      tags:
        - equipment
  /events:
    get:
      summary: Retrieves events
      tags:
        - event
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventRepresentation'
      operationId: get-events
      description: Fetches events by a given query
      parameters:
        - schema:
            type: string
          in: query
          name: name
          description: The name or a substring of the name
        - schema:
            type: number
          in: query
          name: start
          description: The start date as unix timestamp
        - schema:
            type: number
          in: query
          name: end
          description: The end date as unix timestamp
        - schema:
            type: number
          in: query
          name: attendance
          description: The exact attendance figure required
        - schema:
            type: array
          in: query
          name: venueIDs
          description: 'The array of venues required, modifiable via venueCriteria'
        - schema:
            type: string
            enum:
              - all
              - any
          in: query
          name: venueCriteria
          description: 'If all then all venues must be preset, if any then any of the venues match. Should be a comma separated list of venue IDs'
        - schema:
            type: string
          in: query
          name: entsID
          description: The ID of an ent state that must be present
        - schema:
            type: string
          in: query
          name: stateID
          description: The ID of a state that must be present
        - schema:
            type: number
          in: query
          name: startafter
          description: 'The beginning of the start date range, as a unit timestamp'
        - schema:
            type: number
          in: query
          name: startbefore
          description: 'The end of the start date range, as a unit timestamp'
        - schema:
            type: number
          in: query
          name: endafter
          description: 'The beginning of the end date range, as a unit timestamp'
        - schema:
            type: number
          in: query
          name: endbefore
          description: 'The end of the end date range, as a unit timestamp'
        - schema:
            type: number
          in: query
          name: attendanceGreater
          description: The lowest attendance figure that is required
        - schema:
            type: number
          in: query
          name: attendanceLess
          description: The greatest attendance figure permitted
    post:
      summary: Creates a new event
      operationId: post-events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Creates a new event
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                venue:
                  type: string
                start:
                  type: number
                end:
                  type: number
                attendance:
                  type: number
                state:
                  type: string
                ents:
                  type: string
              required:
                - name
                - venue
                - start
                - end
                - attendance
      tags:
        - event
  '/events/{eventID}':
    parameters:
      - schema:
          type: string
        name: eventID
        in: path
        required: true
        description: The unique event ID
    get:
      summary: Fetches a single event instance
      tags:
        - event
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  status:
                    type: string
                    enum:
                      - OK
                      - FAIL
                  event:
                    $ref: '#/components/schemas/EventRepresentation'
                  changelog:
                    type: array
                    items: {}
                required:
                  - status
                  - event
                  - changelog
      operationId: get-events-eventID
      description: Returns the event with its changelog
    patch:
      summary: Updates an event
      operationId: patch-events-eventID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: 'Updates an event and will save its modification in the changelog returned by GET /events/{eventID}'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                start:
                  type: number
                end:
                  type: number
                attendance:
                  type: number
                addVenues:
                  type: array
                  items:
                    type: string
                removeVenues:
                  type: array
                  items:
                    type: string
                ents:
                  type: string
                state:
                  type: string
        description: ''
      tags:
        - event
    delete:
      summary: Deletes an event instance
      operationId: delete-events-eventID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Removes an event instance but will preserve an events changelog as an audit measure
      tags:
        - event
  '/events/{eventID}/comments':
    parameters:
      - schema:
          type: string
        name: eventID
        in: path
        required: true
    get:
      summary: Retrieves comments on an event
      tags:
        - event
        - comment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/CommentRepresentation'
      operationId: get-events-eventID-comments
      description: Returns all comments written for this event
    post:
      summary: Creates a new comment
      operationId: post-events-eventID-comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Creates a new comment on an event. Currently events cannot be ammended once produced
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                category:
                  type: string
                requiresAttention:
                  type: boolean
                body:
                  type: string
              required:
                - body
      tags:
        - event
        - comment
  '/states/{stateID}/events':
    get:
      summary: Fetches all the events for the given state
      tags:
        - event
        - state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventRepresentation'
      operationId: get-states-stateID-events
      description: Fetches all the events which are defined for a given state
    parameters:
      - schema:
          type: string
        name: stateID
        in: path
        required: true
        description: The unique state identifier
  '/venues/{venueID}/events':
    parameters:
      - schema:
          type: string
        name: venueID
        in: path
        required: true
        description: The unique venue identifier
    get:
      summary: Retrieves all events occuring the given venue
      tags:
        - venue
        - event
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventRepresentation'
      operationId: get-venues-venueID-events
      description: Retrieves all events occuring the given venue
  /files:
    get:
      summary: Fetches all files matching a query
      tags:
        - file
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/FileRepresentation'
      operationId: get-files
      description: Fetches all files matching a query. If the query is omitted it will return all files entered on the system
      parameters:
        - schema:
            type: string
          in: query
          name: id
          description: The unique ID of this file
        - schema:
            type: string
          in: query
          name: name
          description: The name of a substring of the name of the file
        - schema:
            type: string
          in: query
          name: filename
          description: The raw filename or a substring of the filename of the uploaded file
        - schema:
            type: number
          in: query
          name: size
          description: 'The size of the file, in bytes'
        - schema:
            type: string
          in: query
          name: type
          description: The type of file uploaded
        - schema:
            type: number
          in: query
          name: date
          description: 'The date of the file upload, expressed as a unix timestamp'
        - schema:
            type: string
          in: query
          name: userid
          description: The identifier of the user who uploaded the file
    post:
      summary: Creates a new file on the system
      operationId: post-files
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: This endpoint creates a new file meta-data entry on the server. This does not actually upload a file. This response will contain an uploadURI in the response where the file should actually be uploaded. The file should be sent as a multipart form data POST request to the uploadURI which encodes the file in the 'data' parameter.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                filename:
                  type: string
                size:
                  type: number
                type:
                  type: string
              required:
                - name
                - filename
                - size
                - type
      tags:
        - file
  '/files/{fileID}':
    parameters:
      - schema:
          type: string
        name: fileID
        in: path
        required: true
        description: The unique file ID
    get:
      summary: Fetches a single file entry
      tags:
        - file
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/FileRepresentation'
      operationId: get-files-fileID
      description: Returns a single file entry containing its download URL as well
    patch:
      summary: Updates properties of a single file
      operationId: patch-files-fileID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Updates details of a single file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
      tags:
        - file
    delete:
      summary: Removes a file entry
      operationId: delete-files-fileID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: 'This endpoint deletes the file meta-data entry and will optionally delete the file uploaded, depending on the servers retention policy for files. '
      tags:
        - file
  '/files/{fileID}/events':
    parameters:
      - schema:
          type: string
        name: fileID
        in: path
        required: true
        description: The unique file ID
    get:
      summary: Retrieves all files associated with the file
      tags:
        - file
        - event
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventRepresentation'
      operationId: get-files-fileID-events
      description: Returns all files that are associated with this file identifier
  '/events/{eventID}/files':
    parameters:
      - schema:
          type: string
        name: eventID
        in: path
        required: true
        description: The unique event identifier
    get:
      summary: Fetches all files associated with one event
      tags:
        - file
        - event
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/FileRepresentation'
      operationId: get-events-eventID-files
      description: Fetches all files associated with one event
    post:
      summary: Attaches a file to an event
      operationId: post-events-eventID-files
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: This endpoint binds an existing file to an existing event
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                fileID:
                  type: string
              required:
                - fileID
      tags:
        - file
        - event
  '/events/{eventID}/files/{fileID}':
    parameters:
      - schema:
          type: string
        name: eventID
        in: path
        required: true
        description: The event ID
      - schema:
          type: string
        name: fileID
        in: path
        required: true
        description: The file ID
    delete:
      summary: Deletes a single file binding
      operationId: delete-events-eventID-files-fileID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Unbinds an event from a file. This does not impact either entity
      tags:
        - event
        - file
  '/events/{eventID}/signups':
    parameters:
      - schema:
          type: string
        name: eventID
        in: path
        required: true
        description: The unique identifier for this event
    get:
      summary: Retrieves all signups present on an event
      tags:
        - event
        - signup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      '':
                        type: array
                        items:
                          $ref: '#/components/schemas/SignupRepresentation'
      operationId: get-events-eventID-signups
      description: Retrieves the list of users currents signed up to this event and their role on the event
      parameters:
        - schema:
            type: string
          in: query
          name: id
          description: The ID of the signup to fetch
        - schema:
            type: number
          in: query
          name: date
          description: 'The date at which the signup was placed, as a unix timestamp'
        - schema:
            type: string
          in: query
          name: userid
          description: The ID of the user signed up to query
        - schema:
            type: number
          in: query
          name: dateRangeBegin
          description: The start range of the signup date
        - schema:
            type: number
          in: query
          name: dateRangeEnd
          description: The end of the range of signup dates
        - schema:
            type: string
          in: query
          name: role
          description: The role for which to fetch all signed up users
    post:
      summary: Signs a user up to the event
      operationId: post-events-eventID-signups
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: This will add the user issuing the request as a member of the event with the given role
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                role:
                  type: string
              required:
                - role
      tags:
        - event
        - signup
  '/events/{eventID}/signups/{signupID}':
    parameters:
      - schema:
          type: string
        name: eventID
        in: path
        required: true
        description: The unique ID of the event on which this signup exists
      - schema:
          type: string
        name: signupID
        in: path
        required: true
        description: The unique identifier of the signup on this event
    get:
      summary: Returns details of a single signup on an event
      tags:
        - event
        - signup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/SignupRepresentation'
      operationId: get-events-eventID-signups-signupID
      description: Returns the properties of a single signup
    patch:
      summary: Update the role of a signup
      operationId: patch-events-eventID-signups-signupID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: 'Updates the role of the signup present on the server, this is the only modifiable property because signups are formed of events, users and roles. '
      tags:
        - event
        - signup
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
    delete:
      summary: Removes this users signup from the event
      operationId: delete-events-eventID-signups-signupID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: This will delete the signup from the server
      tags:
        - event
        - signup
  /states:
    get:
      summary: Retrieves all states currently on the server
      tags:
        - state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/StateRepresentation'
      operationId: get-states
      description: All valid states will
      parameters:
        - schema:
            type: string
          in: query
          name: name
          description: 'The name, or a substring of it, to query'
        - schema:
            type: string
          in: query
          name: icon
          description: The icon used to identify this state
        - schema:
            type: string
          in: query
          name: color
          description: 'The colour used to identify the states, expressed as a hex colour code, with a #'
        - schema:
            type: string
          in: query
          name: id
          description: The unique ID to return a single result
    post:
      summary: Creates a new event state
      operationId: post-states
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Inserts a new event state into the server
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                icon:
                  type: string
                color:
                  type: string
              required:
                - name
                - icon
                - color
      tags:
        - state
  '/states/{stateID}':
    parameters:
      - schema:
          type: string
        name: stateID
        in: path
        required: true
        description: The unique identifier for this state
    get:
      summary: Retrieves properties about a single state
      tags:
        - state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/StateRepresentation'
      operationId: get-states-stateID
      description: Returns the details of a single state
    patch:
      summary: Updates a single state
      operationId: patch-states-stateID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Updates properties of an existing state
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                icon:
                  type: string
                color:
                  type: string
      tags:
        - state
    delete:
      summary: Removes an existing state
      operationId: delete-states-stateID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Deletes an existing state from the system
      tags:
        - state
  /topics:
    get:
      summary: Queries existing topics
      tags:
        - topic
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/TopicRepresentation'
      operationId: get-topics
      description: Fetches all topics matching the given query
      parameters:
        - schema:
            type: string
          in: query
          name: name
          description: 'The name, or a substring of it, to query'
        - schema:
            type: string
          in: query
          name: icon
          description: The icon associated with topics to query
        - schema:
            type: string
          in: query
          name: color
          description: The color code to search by as a 7 character hex colour code. This match is exact
        - schema:
            type: string
          in: query
          name: id
          description: 'The id to fetch if requesting one resource, recommended to use /topics/:id if you know it exists'
        - schema:
            type: string
          in: query
          name: description
          description: 'The description, or a substring of it to query by'
    post:
      summary: Inserts a new topic
      operationId: post-topics
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Creates a new topic and returns the ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                icon:
                  type: string
                color:
                  type: string
                description:
                  type: string
              required:
                - name
                - icon
                - color
                - description
      tags:
        - topic
  '/topics/{topicID}':
    parameters:
      - schema:
          type: string
        name: topicID
        in: path
        required: true
        description: The unique topic identifier
    get:
      summary: Fetches a single topic
      tags:
        - topic
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/TopicRepresentation'
      operationId: get-topics-topicID
      description: Retrieves a single topic from the server
    delete:
      summary: Removes a topic
      operationId: delete-topics-topicID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Deletes a topic from the system
      tags:
        - topic
    patch:
      summary: Updates a topic
      operationId: patch-topics-topicID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Updates the properties of a topic
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                color:
                  type: string
                icon:
                  type: string
                description:
                  type: string
      tags:
        - topic
  /user:
    get:
      summary: Fetches all users on the server
      tags:
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/UserRepresentation'
      operationId: get-user
      description: 'Retrieves all users on the server, optionally with emails and hashes'
      parameters:
        - schema:
            type: string
          in: query
          name: id
          description: 'The id of the user if fetching a single result, recommended to use /user/:id'
        - schema:
            type: string
          in: query
          name: name
          description: The real name of the user to fetch
        - schema:
            type: string
          in: query
          name: username
          description: The username of the user to fetch
        - schema:
            type: string
          in: query
          name: email
          description: The email address of the user to search by
        - schema:
            type: string
          in: query
          name: includeEmail
          description: If emails should be included in the user results
        - schema:
            type: string
          in: query
          name: includeHash
          description: If hashes should be included in the user results
    post:
      summary: Creates a new user instance
      operationId: post-user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: 'Inserts a new complete user into the system. This only creates user metadata, this does not interact with the authentication server. This route is deprecated as users are asserted on login and missing user information will be created. While this route still exists it will be removed in future releases.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                username:
                  type: string
                email:
                  type: string
                hash:
                  type: string
                  description: 'Currently not used, leave blank for now. Authentication is handled by the authentication server and hashes are stored elsewhere'
                profile:
                  type: string
              required:
                - name
                - username
                - email
                - hash
      deprecated: true
      tags:
        - user
  '/user/{userID}':
    parameters:
      - schema:
          type: string
        name: userID
        in: path
        required: true
        description: 'The unique user id, this is their server ID not username or any other identifier'
    get:
      summary: Fetches a single user instance
      tags:
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/UserRepresentation'
      operationId: get-user-userID
      description: Returns a single user if the ID matches
    delete:
      summary: Removes a user
      operationId: delete-user-userID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: 'Deletes user metadata from the server. This is currently deprecated as users should not be managed directly through the gateway. This should be handled via the authentication server but this route is still available. Currently this is the only confirmed way to delete user metadata but this will not prevent users from logging and the user metadata will be recreated with a new identifier on next login. '
      deprecated: true
      tags:
        - user
    patch:
      summary: Updates user metadata
      operationId: patch-user-userID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: 'Updates user metadata. This route is currently deprecated as user metadata is overwritten periodically by the keycloak server. While route is still available it will be removed in future releases. '
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                username:
                  type: string
                email:
                  type: string
                hash:
                  type: string
                profile:
                  type: string
      deprecated: true
      tags:
        - user
  /venues:
    get:
      summary: Fetches all venue matching a query
      tags:
        - venue
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          $ref: '#/components/schemas/VenueRepresentation'
      operationId: get-venues
      description: All venues matching the given query will be returned. When the query is empty all values will be returned
      parameters:
        - schema:
            type: string
          in: query
          name: name
          description: The name or a substring of the name to query by
        - schema:
            type: number
          in: query
          name: capacity
          description: The exact capacity of the venue to search
        - schema:
            type: number
          in: query
          name: approximate_capacity
          description: 'An approximate capacity to search by, values will be around this point with the accuracy being adjusted through the approximate_fuzziness result'
        - schema:
            type: number
          in: query
          name: approximate_fuzziness
          description: How much leniency should be provided either side of approximate_capacity
        - schema:
            type: number
          in: query
          name: minimum_capacity
          description: The minimum capacity allowed to be returned in the request
        - schema:
            type: number
          in: query
          name: maximum_capacity
          description: The maximum capacity allowed in the response
    post:
      summary: Create a new venue
      operationId: post-venues
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: This inserts a new venue entry in the system and returns its ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                capacity:
                  type: number
                color:
                  type: string
              required:
                - name
                - capacity
                - color
      tags:
        - venue
  '/venues/{venueID}':
    parameters:
      - schema:
          type: string
        name: venueID
        in: path
        required: true
        description: The unique venue identifier
    get:
      summary: Fetches venue by ID
      tags:
        - venue
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/VenueRepresentation'
      operationId: get-venues-venueID
      description: Fetches a single venue by ID
    patch:
      summary: Updates a venue
      operationId: patch-venues-venueID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Updates properties of a venue
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                capacity:
                  type: number
                color:
                  type: string
      tags:
        - venue
    delete:
      summary: Removes a venue
      operationId: delete-venues-venueID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDArrayResult'
      description: Deletes a venue from the system
      tags:
        - venue
  /status:
    get:
      summary: Gets the current status of the gateway
      tags:
        - system
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                example: OK 0.0.1
                pattern: 'OK [0-9]+\.[0-9]+\.[0-9]+'
      operationId: get-status
      description: 'Returns the current status of the system. In the current version this will only return OK, optionally followed by the version of the gateway if the properties have been loaded. Otherwise the version will be listed as 0.0.1'
  /whoami:
    get:
      summary: Returns the current user on the system
      tags:
        - system
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  profile:
                    type: string
                  username:
                    type: string
                required:
                  - name
                  - profile
                  - username
      operationId: get-whoami
      description: This returns the properties of the currently authenticated user
components:
  schemas:
    CommentRepresentation:
      type: object
      title: CommentRepresentation
      x-tags:
        - comment
      additionalProperties: false
      properties:
        id:
          type: string
        assetType:
          type: string
        assetID:
          type: string
        poster:
          $ref: '#/components/schemas/UserRepresentation'
        posted:
          type: number
        category:
          type: string
        requiresAttention:
          type: boolean
        attendedDate:
          type: number
        attendedBy:
          $ref: '#/components/schemas/UserRepresentation'
        body:
          type: string
      required:
        - id
        - assetType
        - assetID
        - poster
        - posted
        - body
    StateRepresentation:
      type: object
      title: StateRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
          pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
        icon:
          type: string
      required:
        - id
        - name
        - color
        - icon
    EntStateRepresentation:
      type: object
      title: EntStateRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
          pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
        icon:
          type: string
      required:
        - id
        - name
        - color
        - icon
    TopicRepresentation:
      type: object
      title: TopicRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        color:
          type: string
          pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
        icon:
          type: string
      required:
        - id
        - name
        - description
        - color
        - icon
    UserRepresentation:
      type: object
      title: UserRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        username:
          type: string
        profile:
          type: string
          format: uri
        email:
          type: string
          format: email
        hash:
          type: string
      required:
        - id
        - name
        - username
    EquipmentRepresentation:
      type: object
      title: EquipmentRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        assetID:
          type: string
        name:
          type: string
        manufacturer:
          type: string
        model:
          type: string
        miscIdentifier:
          type: string
        amount:
          type: number
        location:
          $ref: '#/components/schemas/VenueRepresentation'
        locationSpecifier:
          type: string
        manager:
          $ref: '#/components/schemas/UserRepresentation'
        date:
          type: number
        category:
          type: string
      required:
        - id
        - name
        - manufacturer
        - model
        - amount
        - location
        - manager
        - date
        - category
    VenueRepresentation:
      type: object
      title: VenueRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        capacity:
          type: number
        color:
          type: string
          pattern: '^#?([0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?)$'
        user:
          $ref: '#/components/schemas/UserRepresentation'
      required:
        - id
        - name
        - capacity
        - user
    FileRepresentation:
      type: object
      title: FileRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        filename:
          type: string
        size:
          type: number
        mime:
          type: string
        owner:
          $ref: '#/components/schemas/UserRepresentation'
        type:
          type: string
        date:
          type: number
        downloadURL:
          type: string
      required:
        - id
        - name
        - filename
        - size
        - mime
        - owner
        - type
        - date
        - downloadURL
    SignupRepresentation:
      title: SignupRepresentation
      type: object
      properties:
        id:
          type: string
        user:
          $ref: '#/components/schemas/UserRepresentation'
        event:
          $ref: '#/components/schemas/EventRepresentation'
        role:
          type: string
        date:
          type: number
      required:
        - id
        - user
        - event
        - role
        - date
    EventRepresentation:
      type: object
      title: EventRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        start:
          type: number
        end:
          type: number
        venues:
          type: array
          items:
            $ref: '#/components/schemas/VenueRepresentation'
        attendance:
          type: number
        ents:
          $ref: '#/components/schemas/EntStateRepresentation'
        state:
          $ref: '#/components/schemas/StateRepresentation'
      required:
        - id
        - name
        - start
        - end
        - venues
        - attendance
    VenueReportRepresentation:
      type: object
      title: VenueReportRepresentation
      additionalProperties: false
      properties:
        id:
          type: string
        equipment:
          $ref: '#/components/schemas/EquipmentRepresentation'
        report:
          type: string
        reporter:
          $ref: '#/components/schemas/UserRepresentation'
        date:
          type: number
        state:
          type: string
        resolvedDate:
          type: number
        resolver:
          $ref: '#/components/schemas/UserRepresentation'
      required:
        - id
        - equipment
        - report
        - reporter
        - date
        - state
    Result:
      title: Result
      type: object
      properties:
        status:
          type: string
          enum:
            - OK
            - FAILED
        result: {}
      required:
        - status
    IDArrayResult:
      title: IDArrayResult
      allOf:
        - $ref: '#/components/schemas/Result'
        - type: object
          properties:
            result:
              type: array
              items:
                type: string
          required:
            - result
  securitySchemes:
    uems:
      type: openIdConnect
      openIdConnectUrl: 'https://auth.uems.xiomi.org/realms/uems/protocol/openid-connect/auth'
      description: 'Authentication is provided by keycloak. The URL shown is currently provisional based on whether this system works. When self hosting this is available at :8080 hosting'
tags:
  - name: ents
  - name: equipment
  - name: event
  - name: comment
  - name: file
  - name: signup
  - name: state
  - name: topic
  - name: user
  - name: venue
  - name: system