openapi: 3.0.0
info:
  description: |
    Welcome to the HumHub topic module API reference.
  version: 1.0.0
  title: HumHub - Topic API
  contact:
    email: info@humhub.com
  license:
    name: AGPLv2
    url: https://www.humhub.org/en/licences
tags:
  - name: Topic
    description: API to access and manage topic information.
    externalDocs:
      description: Find out more
      url: http://docs.humhub.org
paths:
  /topic:
    get:
      tags:
        - Topic
      summary: Find all topics
      description: ""
      parameters:
        - $ref: common.yaml#/components/parameters/pageParam
        - $ref: common.yaml#/components/parameters/limitParam
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Topic"
            application/xml:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Topic"
  "/topic/{id}":
    get:
      tags:
        - Topic
      summary: Get topic by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of topic
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Topic"
            application/xml:
              schema:
                $ref: "#/components/schemas/Topic"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Topic not found
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Topic not found
    put:
      tags:
        - Topic
      summary: Update existing topic
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of topic
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Api topic
        description: Topic name
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Topic"
            application/xml:
              schema:
                $ref: "#/components/schemas/Topic"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: You are not allowed to manage this topic!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: You are not allowed to manage this topic!
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Topic not found
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Topic not found
        "422":
          description: Validation failed
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while update topic!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while update topic!
    delete:
      tags:
        - Topic
      summary: Delete topic by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of topic
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Topic successfully deleted!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Topic successfully deleted!
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: You are not allowed to delete this topic!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: You are not allowed to delete this topic!
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Topic not found
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Topic not found
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while delete topic!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while delete topic!
  "/topic/container/{containerId}":
    get:
      tags:
        - Topic
      summary: Get all topics by container
      description: ""
      parameters:
        - $ref: common.yaml#/components/parameters/pageParam
        - $ref: common.yaml#/components/parameters/limitParam
        - in: path
          name: containerId
          description: The id of container
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Topic"
            application/xml:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Topic"
    post:
      tags:
        - Topic
      summary: Create new topic
      description: ""
      parameters:
        - in: path
          name: containerId
          description: The id of container
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: Api topic
        description: Topic info
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Topic"
            application/xml:
              schema:
                $ref: "#/components/schemas/Topic"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: You are not allowed to create topic!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: You are not allowed to create topic!
        "422":
          description: Validation failed
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while save topic!
            application/xml:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while save topic!
servers:
  - url: /api/v1
components:
  securitySchemes:
    _ref: common.yaml#/securityDefinitions
  schemas:
    Topic:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          example: 1
        name:
          type: string
          readOnly: true
          example: Api topic
