diff --git a/doc/openapi3_0.yaml b/doc/openapi3_0.yaml new file mode 100644 index 0000000..bd611d4 --- /dev/null +++ b/doc/openapi3_0.yaml @@ -0,0 +1,337 @@ +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/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: 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: + application/json: + schema: + $ref: '#/components/schemas/AppointmentList' + '400': + description: invalid input + '500': + description: server fault + summary: Fetch event list + /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/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 + '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 +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 \ No newline at end of file