engelsystem/resources/api/openapi.yml

405 lines
11 KiB
YAML
Raw Normal View History

2023-05-21 12:40:36 +02:00
openapi: 3.0.3
info:
version: 0.0.1-beta
title: Engelsystem
description: |
2023-07-22 22:47:55 +02:00
This API is as stable as a **beta** version might be.
2023-05-21 12:40:36 +02:00
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
2023-05-21 12:40:36 +02:00
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key from settings
responses:
UnauthorizedError: # 401
2023-05-21 12:40:36 +02:00
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'
2023-05-21 12:40:36 +02:00
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
2023-05-21 12:40:36 +02:00
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.
2023-05-21 12:40:36 +02:00
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
2023-05-21 12:40:36 +02:00
example: 2023-05-13T13:37:42.000000Z
updated_at:
type: string
nullable: true
format: date-time
description: DateTime in ISO-8601 format
2023-05-21 12:40:36 +02:00
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
Location:
type: object
properties:
id:
type: integer
example: 42
name:
type: string
example: Heaven
url:
type: string
example: https://example.com/location/42
description: Link of the location 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.
starts_at:
type: string
format: date-time
description: DateTime in ISO-8601 format
example: 2023-05-13T14:00:00.000000Z
ends_at:
type: string
format: date-time
description: DateTime in ISO-8601 format
example: 2023-05-13T16:00:00.000000Z23
location:
$ref: '#/components/schemas/Location'
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
- starts_at
- ends_at
- location
- 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
2023-05-21 12:40:36 +02:00
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'
2023-05-21 12:40:36 +02:00
/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'
2023-05-21 12:40:36 +02:00
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
/locations:
get:
tags:
- shift
summary: Get a list of locations
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Location'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
/locations/{id}/shifts:
parameters:
- name: id
in: path
required: true
description: The locations identifier
example: 42
schema:
type: integer
get:
tags:
- shift
summary: Get all shifts in the requested location
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'