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