openapi: 3.0.3 info: version: 0.0.1-beta title: Engelsystem description: | This API is as stable as a **beta** version might be. It could burst into flames and morph into a monster at any second! (But we try to keep it somewhat consistent, at least during events). contact: name: GitHub Issues url: https://github.com/engelsystem/engelsystem/issues license: name: GPL 2.0 # identifier: GPL-2.0 servers: - url: /api/v0-beta description: This server - url: http://localhost:5080/api/v0-beta description: Your local dev instance tags: - name: news description: News and meeting announcements - name: shift description: Event shifts and location components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key from settings responses: UnauthorizedError: # 401 description: Access token is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' ForbiddenError: # 403 description: The client is not allowed to access content: application/json: schema: $ref: '#/components/schemas/Error' NotFoundError: # 404 description: This resource can not be found content: application/json: schema: $ref: '#/components/schemas/Error' NotImplementedError: # 405 description: This endpoint or method is not implemented content: application/json: schema: $ref: '#/components/schemas/Error' schemas: AngelType: type: object properties: id: type: integer example: 42 name: type: string example: Angel description: type: string example: Meta-Group of all registered Angels url: type: string example: https://example.com/angeltype/42 description: Link to the page of the given angeltype. required: - id - name - description - url Error: type: object properties: message: type: string News: type: object properties: id: type: integer example: 42 title: type: string example: First helper introduction text: type: string example: | The first introduction meeting takes place at the **Foo Hall** at 13:37. Please bring your own seating as it might take some time. description: | The complete news text with markdown formatting. Might include a `[more]` tag to be used as a separator which must be removed from the text when shown. is_meeting: type: boolean example: true description: Whether or not the news announces a meeting is_pinned: type: boolean example: false description: True if the news is pinned to the top is_highlighted: type: boolean example: false description: True if the news should be highlightet and shown on the dashboard created_at: type: string format: date-time description: DateTime in ISO-8601 format example: 2023-05-13T13:37:42.000000Z updated_at: type: string nullable: true format: date-time description: DateTime in ISO-8601 format example: 2023-05-13T23:00:00.000000Z url: type: string example: https://example.com/news/42 description: Direct link to the news page required: - id - title - text - is_meeting - is_pinned - is_highlighted - created_at - updated_at - url Room: type: object properties: id: type: integer example: 42 name: type: string example: Heaven url: type: string example: https://example.com/rooms/42 description: Link of the room start page required: - id - name - url Shift: type: object properties: id: type: integer example: 42 title: type: string example: Cleanup the venue description: type: string example: You clean up the venue after the event, its fun, we promise! description: | Shift description, should be added to the shift type description as it might be empty. Normally contains additional information for a specific shift / task. start: type: string format: date-time description: DateTime in ISO-8601 format example: 2023-05-13T14:00:00.000000Z end: type: string format: date-time description: DateTime in ISO-8601 format example: 2023-05-13T16:00:00.000000Z23 room: $ref: '#/components/schemas/Room' shift_type: $ref: '#/components/schemas/ShiftType' created_at: type: string nullable: true format: date-time description: DateTime in ISO-8601 format example: 2023-05-13T13:37:42.000000Z updated_at: type: string nullable: true format: date-time description: DateTime in ISO-8601 format example: 2023-05-13T23:00:00.000000Z entries: type: array description: Can be empty (for example on Schedule import of unused room) items: $ref: '#/components/schemas/ShiftEntry' url: type: string example: https://example.com/shifts/42 description: Direct link of the shift required: - id - title - description - start - end - room - shift_type - created_at - updated_at - entries - url ShiftEntry: type: object properties: users: type: array items: $ref: '#/components/schemas/User' type: $ref: '#/components/schemas/AngelType' needs: type: integer description: | Number of users needed for the shift. Can be more than users count when not full, less when overbooked or 0 when additional users have been added. example: 3 required: - users - type - needs ShiftType: type: object properties: id: type: integer example: 42 name: type: string example: Build-Up description: type: string example: This is a generic build-up shift, mostly involving heavy lifting. required: - id - name - description User: type: object properties: id: type: integer example: 42 name: type: string example: HelpfulUser first_name: type: string nullable: true example: Helpful last_name: type: string nullable: true example: User pronoun: type: string nullable: true example: They/Them description: Should be displayed where possible to allow users to be addressed properly contact: type: object properties: dect: type: string nullable: true example: 4242 description: The DECT number is a short internal number where users can be easily reached mobile: type: string nullable: true example: 1234567890 url: type: string example: https://example.com/users/42 description: Links to the users profile page required: - id - name - first_name - last_name - pronoun - contact - url security: - bearerAuth: [ ] paths: /angeltypes: get: tags: - shift summary: Get a list of angeltypes responses: '200': description: Ok content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AngelType' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' /news: get: tags: - news summary: Get a list of all news responses: '200': description: Ok content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/News' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' /rooms: get: tags: - shift summary: Get a list of rooms responses: '200': description: Ok content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Room' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' /rooms/{id}/shifts: parameters: - name: id in: path required: true description: The rooms identifier example: 42 schema: type: integer get: tags: - shift summary: Get all shifts in the requested room responses: '200': description: Ok content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Shift' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError'