swagger: '2.0'
info:
  description: |
    Welcome to the HumHub calendar module API reference.

  version: 1.0.0
  title: HumHub - Calendar API
  contact:
    email: info@humhub.com
  license:
    name: AGPLv2
    url: 'https://www.humhub.org/en/licences'
basePath: /api/v1

paths:
  '/calendar':
    get:
      tags:
        - Calendar
      summary: Find all calendars entries
      description: ''
      produces:
        - application/json
        - application/xml
      parameters:
        - $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/pageParam'
        - $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/limitParam'
      responses:
        '200':
          description: Success
          schema:
            type: object
            properties:
              total:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/totalProperty'
              page:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/pageProperty'
              pages:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/pagesProperty'
              links:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/linksProperty'
              results:
                type: array
                items:
                  $ref: '#/definitions/CalendarEntry'

  '/calendar/container/{id}':
    get:
      tags:
        - Calendar
      summary: Find all calendar entries by container
      description: ''
      produces:
        - application/json
        - application/xml
      parameters:
        - name: id
          in: path
          description: ID of content container
          required: true
          type: integer
        - $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/content.yaml#/components/parameters/topicsParam'
        - $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/pageParam'
        - $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/limitParam'
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              total:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/totalProperty'
              page:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/pageProperty'
              pages:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/pagesProperty'
              links:
                $ref: 'https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/properties/linksProperty'
              results:
                type: array
                items:
                  $ref: '#/definitions/CalendarEntry'
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Content container not found!

    post:
      tags:
        - Calendar entry
      summary: Create new calendar entry
      description: ''
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          type: integer
        - $ref: "#/definitions/CalendarEntryPostParams"
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/CalendarEntry"
        403:
          description: Forbidden
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 403
              message:
                type: string
                example: You are not allowed to create calendar entry!
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Content container not found!
        422:
          description: Validation failed
        500:
          description: Internal server error
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 500
              message:
                type: string
                example: Internal error while save calendar entry!

    delete:
      tags:
        - Calendar
      summary: Deletes a calendar entries by container
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: The id of content container
          required: true
          type: integer
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 200
              message:
                type: string
                example: Records successfully deleted!
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Content container not found!

  '/calendar/entry/{id}':
    get:
      tags:
        - Calendar entry
      summary: Get calendar entry by id
      description: ''
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: The id of the calendar entry
          required: true
          type: integer
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/CalendarEntry"
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Calendar entry not found

    put:
      tags:
        - Calendar entry
      summary: Update calendar entry by id
      description: ''
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: The id of the calendar entry
          required: true
          type: integer
        - $ref: "#/definitions/CalendarEntryPutParams"
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/CalendarEntry"
        403:
          description: Forbidden
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 403
              message:
                type: string
                example: You are not allowed to edit this calendar entry!
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Calendar entry not found
        422:
          description: Validation failed
        500:
          description: Internal server error
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 500
              message:
                type: string
                example: Internal error while update calendar entry!

    delete:
      tags:
        - Calendar entry
      summary: Delete the calendar entry by id
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: The id of calendar entry
          required: true
          type: integer
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 200
              message:
                type: string
                example: Calendar entry successfully deleted!
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Calendar entry not found

#-----------------------------------------------------------------------------------------------------------------------
# Begin Calendar Entry Management
#-----------------------------------------------------------------------------------------------------------------------

  '/calendar/entry/{id}/upload-files':
    post:
      tags:
        - Calendar entry management
      summary: Attach files to calendar entry
      description: ''
      produces:
        - application/json
      consumes:
        - multipart/form-data
      parameters:
        - in: path
          name: id
          description: The id of the calendar entry
          required: true
          type: integer
        - in: formData
          name: files
          type: array
          required: true
          description: The files to upload.
          items:
            type: file
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 200
              message:
                type: string
                example: Files successfully uploaded.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: No files to upload.
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Content record not found!
        500:
          description: Internal server error
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 500
              message:
                type: string
                example: Internal error while saving file.

  '/calendar/entry/{id}remove-file/{fileId}':
    delete:
      tags:
        - Calendar entry management
      summary: Remove file from calendar entry
      description: ''
      produces:
        - application/json
      parameters:
       - in: path
         name: id
         description: The id of the calendar entry
         required: true
         type: integer
       - in: path
         name: fileId
         required: true
         description: The id of file to remove.
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 200
              message:
                type: string
                example: File successfully removed.
        403:
          description: Forbidden
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 403
              message:
                type: string
                example: Insufficient permissions!
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Could not find requested content record or file!
        500:
          description: Internal server error
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 500
              message:
                type: string
                example: Internal error while removing file.

#-----------------------------------------------------------------------------------------------------------------------
# Begin Participants
#-----------------------------------------------------------------------------------------------------------------------

  '/calendar/entry/{id}/respond':
    post:
      tags:
        - Participants
      summary: Change the user participant
      description: ''
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          description: The id of the calendar entry
          required: true
          type: integer
        - in: body
          name: body
          required: true
          schema:
            type: object
            required:
              - type
            properties:
              type:
                type: integer
                format: int64
                enum: [0,1,2,3]
                example: 3
                description: >
                  Participant type:
                   * 1 - decline.
                   * 2 - maybe.
                   * 3 - accept.
                   * 0 - remove from participants.
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 200
              message:
                type: string
                example: Participation successfully changed.
        400:
          description: Bad request
        404:
          description: Not found
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Calendar entry not found

securityDefinitions:
  $ref: "https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/securityDefinitions"

definitions:
  CalendarEntry:
    type: object
    properties:
      id:
        type: integer
        format: int64
        readOnly: true
        example: 6
      title:
        type: string
        example: Space event by API
      description:
        type: string
        example: Space event by API description
      start_datetime:
        type: string
        format: datetime
        example: "2019-02-27 00:00:00"
      end_datetime:
        type: string
        format: datetime
        example: "2019-02-28 23:59:00"
      all_day:
        type: integer
        format: int64
        example: 1
      participation_mode:
        type: integer
        format: int64
        example: 2
      color:
        type: string
        example: "#6fdbe8"
      allow_decline:
        type: integer
        format: int64
        example: 1
      allow_maybe:
        type: integer
        format: int64
        example: 1
      time_zone:
        type: string
        example: America/Los_Angeles
      participant_info:
        type: string
        example: ""
      closed:
        type: integer
        format: int64
        example: 0
      max_participants:
        type: string
        example: null
      location:
        type: string
        example: null
      content:
        $ref: "https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/content.yaml#/definitions/Content"

  CalendarEntryPostParams:
    in: body
    name: body
    required: true
    description: Calendar entry information
    schema:
      type: object
      required:
        - CalendarEntry
        - CalendarEntryForm
      properties:
        CalendarEntry:
          type: object
          required:
            - title
          properties:
            title:
              type: string
              example: Api calendar event
            description:
              type: string
              example: Api calendar event description
            color:
              type: string
              example: "#6fdbe8"
            all_day:
              type: integer
              format: int64
              example: 0
            participation_mode:
              type: integer
              format: int64
              example: 2
            max_participants:
              type: integer
              format: int64
              example: null
            allow_decline:
              type: integer
              format: int64
              example: 1
            allow_maybe:
              type: integer
              format: int64
              example: 1
            participant_info:
              type: string
              example: ""
        CalendarEntryForm:
          type: object
          required:
            - start_date
            - end_date
          properties:
            is_public:
              type: integer
              format: int64
              example: 1
            start_date:
              type: string
              format: date
              example: "2019-03-23"
            start_time:
              type: string
              example: "10:00"
            end_date:
              type: string
              format: date
              example: "2019-03-25"
            end_time:
              type: string
              example: "20:30"
            timeZone:
              type: string
              example: America/Los_Angeles
            forceJoin:
              type: integer
              format: int64
              example: 0
            topics:
              type: array
              items:
                type: integer
                format: int64
                example: 3
        content:
          $ref: "https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/content.yaml#/definitions/Content"


  CalendarEntryPutParams:
    in: body
    name: body
    required: true
    description: Calendar entry information
    schema:
      type: object
      required:
        - CalendarEntry
        - CalendarEntryForm
      properties:
        CalendarEntry:
          type: object
          required:
            - title
          properties:
            title:
              type: string
              example: Api calendar event
            description:
              type: string
              example: Api calendar event description
            color:
              type: string
              example: "#6fdbe8"
            all_day:
              type: integer
              format: int64
              example: 0
            participation_mode:
              type: integer
              format: int64
              example: 2
            max_participants:
              type: integer
              format: int64
              example: null
            allow_decline:
              type: integer
              format: int64
              example: 1
            allow_maybe:
              type: integer
              format: int64
              example: 1
            participant_info:
              type: string
              example: ""
        CalendarEntryForm:
          type: object
          required:
            - start_date
            - end_date
          properties:
            is_public:
              type: integer
              format: int64
              example: 1
            start_date:
              type: string
              format: date
              example: "2019-03-23"
            start_time:
              type: string
              example: "10:00"
            end_date:
              type: string
              format: date
              example: "2019-03-25"
            end_time:
              type: string
              example: "20:30"
            timeZone:
              type: string
              example: America/Los_Angeles
            forceJoin:
              type: integer
              format: int64
              example: 0
            sendUpdateNotification:
              type: integer
              format: int64
              example: 0
            topics:
              type: array
              items:
                type: integer
                format: int64
                example: 3
        content:
          $ref: "https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/content.yaml#/definitions/Content"
