405 lines
11 KiB
YAML
405 lines
11 KiB
YAML
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'
|