SRSoftware
/
OpenCloudCal
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
87 Commits
1 Branch
0 Tags
1.3 MiB
 
 
 
 
 
 
Branch: main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
OpenCloudCal/doc/openapi3_0.yaml

427 lines
12 KiB
Raw Permalink Blame History

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