engelsystem/resources/api/openapi.yml

374 lines
9.0 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'
NotImplementedError: # 501
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/news/42
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.
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
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
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!
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
entries:
type: array
items:
$ref: '#/components/schemas/ShiftEntry'
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
url:
type: string
example: https://example.com/shifts/42
required:
- id
- title
- description
- start
- end
- entries
- room
- shift_type
- created_at
- updated_at
- url
ShiftEntry:
type: object
properties:
user:
$ref: '#/components/schemas/User'
type:
$ref: '#/components/schemas/AngelType'
required:
- user
- type
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
contact:
type: object
properties:
dect:
type: string
nullable: true
example: 4242
mobile:
type: string
nullable: true
example: 1234567890
url:
type: string
example: https://example.com/users/42
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'
/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 room identifier
example: 42
schema:
type: integer
get:
tags:
- shift
summary: Get all shifts in the 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'