# This file contains the API definitions for the Zulip REST API.
#
# For details on the OpenAPI specification, see http://swagger.io/specification
#
# Our own documentation lives at
#
#   https://zulip.readthedocs.io/en/latest/subsystems/swagger-api-docs.html
#

openapi: 3.0.1
info:
  version: 1.0.0
  title: Zulip REST API
  description: Powerful open source group chat
  contact:
    url: https://zulipchat.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: 'https://your.zulip.server/api/v1'

#######################
# Endpoint definitions
#######################
paths:
  /messages/{message_id}:
    patch:
      description: Edit a message that has already been sent.
      parameters:
      - name: message_id
        in: path
        description: The ID of the message that you wish to edit/update.
        schema:
          type: integer
        example: 42
        required: true
      - name: subject
        in: query
        description: |
          The topic of the message. Only required for stream messages.
          Maximum length of 60 characters.
        schema:
          type: string
          default:
        example: Castle
      - name: propagate_mode
        in: query
        description: |
          Which message(s) should be edited: just the one indicated in
          `message_id`, messages in the same topic that had been sent after
          this one, or all of them.
        schema:
          type: string
          enum:
          - change_one
          - change_later
          - change_all
          default: change_one
        example: change_all
      - name: content
        in: query
        description: Message's new body.
        schema:
          type: string
        example: Hello
      security:
      - basicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/SimpleSuccess'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonError'
                - properties:
                    msg:
                      enum:
                      - Your organization has turned off message editing
                      - You don't have permission to edit this message
                      - The time limit for editing this message has past
                      - Nothing to change
                      - Topic can't be empty
components:
  #######################
  # Security definitions
  #######################
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: |
        Basic authentication, with the user's email as the username, and the
        API key as the password. The API key can be fetched using the
        `/fetch_api_key` or `/dev_fetch_api_key` endpoints.
  schemas:
    JsonResponse:
      type: object
      properties:
        result:
          type: string

    JsonSuccess:
      allOf:
      - $ref: '#/components/schemas/JsonResponse'
      - required:
        - result
        - msg
      - properties:
          result:
            enum:
            - success
          msg:
            type: string

    JsonError:
      allOf:
      - $ref: '#/components/schemas/JsonResponse'
      - required:
        - result
        - msg
      - properties:
          result:
            enum:
            - error
          msg:
            type: string

  ###################
  # Shared responses
  ###################
  responses:
    SimpleSuccess:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonSuccess'