427 lines
12 KiB
YAML
427 lines
12 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: OpenCloucCal API
|
||
description: |-
|
||
The OpenCloucCal API describes the Backend of the OpenCloudCal webservice,
|
||
which is both used for the frontend and may also
|
||
be used for third-party services
|
||
license:
|
||
name: MIT license
|
||
url: https://git.srsoftware/REPO/License.md
|
||
version: 1.0.0
|
||
servers:
|
||
- url: https://cal.srsoftware.de
|
||
- url: http://localhost:8080
|
||
paths:
|
||
/api/event:
|
||
delete:
|
||
description: Deletes the specified element from the list of events.
|
||
parameters:
|
||
- description: the appointment id
|
||
in: query
|
||
name: id
|
||
required: true
|
||
schema:
|
||
example: 42
|
||
format: int64
|
||
type: number
|
||
- description: title of the event as kind of confirmation
|
||
in: header
|
||
name: title
|
||
required: true
|
||
schema:
|
||
example: this will not confirm
|
||
format: string
|
||
responses:
|
||
'200':
|
||
description: successfull operation
|
||
'400':
|
||
description: id missing
|
||
'404':
|
||
description: invalid id (no such event)
|
||
'412':
|
||
description: mismatching title (no confirmation)
|
||
'500':
|
||
description: server fault
|
||
summary: remove an event
|
||
get:
|
||
parameters:
|
||
- description: the appointment id
|
||
in: query
|
||
name: id
|
||
required: true
|
||
schema:
|
||
example: 42
|
||
format: int64
|
||
type: number
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentList'
|
||
'400':
|
||
description: invalid input
|
||
'500':
|
||
description: server fault
|
||
summary: get an event with all details
|
||
patch:
|
||
parameters:
|
||
- description: copy of the title
|
||
in: header
|
||
name: title
|
||
schema:
|
||
example: Demolition of the earth
|
||
type: string
|
||
requestBody:
|
||
description: update an appointment.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentList'
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentList'
|
||
'400':
|
||
description: invalid input
|
||
'500':
|
||
description: server fault
|
||
summary: update the specified event
|
||
post:
|
||
parameters:
|
||
- description: copy of the title
|
||
in: header
|
||
name: title
|
||
schema:
|
||
example: Demolition of the earth
|
||
type: string
|
||
requestBody:
|
||
description: Create a new appointment. Id must be set to 0 (number zero).
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentList'
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentList'
|
||
'400':
|
||
description: invalid input
|
||
'500':
|
||
description: server fault
|
||
summary:
|
||
store a new event in the database
|
||
/api/event/ical:
|
||
get:
|
||
parameters:
|
||
- description: the appointment id
|
||
in: query
|
||
name: id
|
||
required: true
|
||
schema:
|
||
example: 42
|
||
format: int64
|
||
type: number
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
text/calendar:
|
||
schema:
|
||
description: event in ical format
|
||
example: |-
|
||
BEGIN:VCALENDAR
|
||
VERSION:2.0
|
||
PRODID:OpenCloudCal
|
||
BEGIN:VEVENT
|
||
UID:42@cal.srsoftware.de
|
||
DTSTART:20241230T100757Z
|
||
DTEND:20241231T100757Z
|
||
SUMMARY:Demolition of the earth
|
||
END:VEVENT
|
||
END:VCALENDAR
|
||
type: string
|
||
'400':
|
||
description: invalid input
|
||
'500':
|
||
description: server fault
|
||
summary: get an event as ical file
|
||
|
||
/api/events/ical:
|
||
get:
|
||
description: |-
|
||
Get a list of events from the server in ICAL format.
|
||
|
||
Filters may be applied by using request parameters.
|
||
parameters:
|
||
- description: Filter keywords. Only events having all provided tags are listed
|
||
example: magrathea,heartofgold
|
||
in: query
|
||
name: tags
|
||
required: false
|
||
schema:
|
||
format: comma-separated values
|
||
type: string
|
||
- description: start time. Only events after this date time are returned
|
||
example: 2024-12-30T10:32
|
||
in: query
|
||
name: start
|
||
required: false
|
||
schema:
|
||
format: date-time
|
||
type: string
|
||
- description: |-
|
||
Return past events, if set. Allowed values:
|
||
* all → return all events
|
||
* [n]m – return events including the last n months
|
||
* [n]y - return events including the last n years
|
||
example: 2m
|
||
in: query
|
||
name: past
|
||
required: false
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
text/calendar:
|
||
schema:
|
||
description: event list in ical format
|
||
example: |-
|
||
BEGIN:VCALENDAR
|
||
VERSION:2.0
|
||
PRODID:OpenCloudCal
|
||
BEGIN:VEVENT
|
||
UID:42@cal.srsoftware.de
|
||
DTSTART:20241230T100757Z
|
||
DTEND:20241231T100757Z
|
||
SUMMARY:Demolition of the earth
|
||
END:VEVENT
|
||
END:VCALENDAR
|
||
type: string
|
||
'400':
|
||
description: invalid input
|
||
'500':
|
||
description: server fault
|
||
summary: Fetch event list
|
||
/api/events/json:
|
||
get:
|
||
description: |-
|
||
Get a list of events from the server in JSON format.
|
||
|
||
Filters may be applied by using request parameters.
|
||
parameters:
|
||
- description: Maximum number of appointments to return
|
||
example: 100
|
||
in: query
|
||
name: count
|
||
required: false
|
||
schema:
|
||
format: int32
|
||
type: number
|
||
- description: skip number of appointments when listing
|
||
example: 50
|
||
in: query
|
||
name: offset
|
||
required: false
|
||
schema:
|
||
format: int32
|
||
type: number
|
||
- description: |-
|
||
Return past events, if set. Allowed values:
|
||
* all → return all events
|
||
* [n]m – return events including the last n months
|
||
* [n]y - return events including the last n years
|
||
example: 2m
|
||
in: query
|
||
name: past
|
||
required: false
|
||
schema:
|
||
type: string
|
||
- description: start time. Only events after this date time are returned
|
||
example: 2024-12-30T10:32
|
||
in: query
|
||
name: start
|
||
required: false
|
||
schema:
|
||
format: date-time
|
||
type: string
|
||
- description: Filter keywords. Only events having all provided tags are listed
|
||
example: magrathea,heartofgold
|
||
in: query
|
||
name: tags
|
||
required: false
|
||
schema:
|
||
format: comma-separated values
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentList'
|
||
'400':
|
||
description: invalid input
|
||
'500':
|
||
description: server fault
|
||
summary:
|
||
Fetch event list
|
||
/api/tags:
|
||
get:
|
||
description: list tags
|
||
parameters:
|
||
- description: substring to search in tags
|
||
example: rock
|
||
in: query
|
||
name: infix
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: successful operation
|
||
content:
|
||
application/json:
|
||
schema:
|
||
description: keywords that describe the event. may be used to filter events
|
||
example:
|
||
- GlamRock
|
||
- HardRock
|
||
- Rockabilly
|
||
- RockNRoll
|
||
items:
|
||
type: string
|
||
type: array
|
||
'400':
|
||
description: invalid input
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: string
|
||
example: {"message":"No infix set in method call parameters"}
|
||
|
||
components:
|
||
schemas:
|
||
Appointment:
|
||
description: an Event
|
||
type: object
|
||
properties:
|
||
id:
|
||
description: unique identifier of the appointment
|
||
example: 42
|
||
format: int64
|
||
type: number
|
||
title:
|
||
description: summary of the item
|
||
example: Demolition of the earth
|
||
type: string
|
||
description:
|
||
description: a text describing the event
|
||
example: Have your towel ready!
|
||
type: string
|
||
start:
|
||
description: date time when the event is scheduled to begin
|
||
format: date-time
|
||
type: string
|
||
end:
|
||
description: date time when the event is scheduled to end
|
||
format: date-time
|
||
type: string
|
||
location:
|
||
description: text describing the location of the event, i.e. address
|
||
example: Cottingto
|
||
type: string
|
||
coords:
|
||
$ref: '#/components/schemas/Coords'
|
||
attachments:
|
||
items:
|
||
$ref: '#/components/schemas/Attachment'
|
||
type: array
|
||
links:
|
||
description: list of links to content related to the event
|
||
items:
|
||
$ref: '#/components/schemas/Link'
|
||
type: array
|
||
tags:
|
||
description: keywords that describe the event. may be used to filter events
|
||
example:
|
||
- DouglasAdams
|
||
- Hitchhiker
|
||
- Guide
|
||
- Galaxy
|
||
items:
|
||
type: string
|
||
type: array
|
||
required:
|
||
- id
|
||
- location
|
||
- start
|
||
- title
|
||
AppointmentList:
|
||
description: list of appointments
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Appointment'
|
||
Attachment:
|
||
description: |-
|
||
A link to a file additional information related to the event.
|
||
|
||
May be used for images, pdfs or anything apart from links to other websites.
|
||
type: object
|
||
properties:
|
||
mime:
|
||
description: MIME type of the attachment
|
||
type: string
|
||
example: image/png
|
||
url:
|
||
description: attachment URL
|
||
example: https://example.com/some/image.png
|
||
format: url
|
||
type: string
|
||
Coords:
|
||
description: location of the event site in a global coordinate system (WGS84)
|
||
type: object
|
||
properties:
|
||
latitude:
|
||
example: 11.5928
|
||
format: float
|
||
type: number
|
||
longitude:
|
||
example: 50.731
|
||
format: float
|
||
type: number
|
||
Ical:
|
||
description: event list in ical format
|
||
example: |-
|
||
BEGIN:VCALENDAR
|
||
VERSION:2.0
|
||
PRODID:OpenCloudCal
|
||
BEGIN:VEVENT
|
||
UID:42@cal.srsoftware.de
|
||
DTSTART:20241230T100757Z
|
||
DTEND:20241231T100757Z
|
||
SUMMARY:Demolition of the earth
|
||
END:VEVENT
|
||
END:VCALENDAR
|
||
type: string
|
||
Link:
|
||
description: hyperlink to content related to an event
|
||
properties:
|
||
description:
|
||
description: text describing the link target
|
||
example: Wikipedia article
|
||
type: string
|
||
url:
|
||
description: the target of the link
|
||
example: https://en.wikipedia.org/wiki/The_Hitchhiker's_Guide_to_the_Galaxy
|
||
type: string |