Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/zerver/openapi/zulip.yaml

652 lines
21 KiB
YAML
Raw Normal View History

api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
# This file contains the API definitions for the Zulip REST API.
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
#
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
# For details on the OpenAPI specification, see http://swagger.io/specification
Explain how to add Swagger REST API doc coverage in zulip.yaml. Introduce Swagger UI and the Swagger/OpenAPI specification. Explain the structure of zulip.yaml and show examples of different sections of the file. This is a new file in /docs not yet included in the Read the Docs table of contents. Where it should go should be determined as we iterate on the Swagger UI integration and expand REST API doc coverage using it. For more on Swagger UI and how Zulip uses it, see: https://github.com/zulip/zulip/issues/3474 https://github.com/zulip/zulip/pull/3397 With some minor tweaks to advertise this by tabbott.
2017-02-24 03:39:44 +01:00
#
# Our own documentation lives at
#
docs: Rename Swagger to OpenAPI in the dev docs' titles.
2018-05-15 20:54:48 +02:00
# https://zulip.readthedocs.io/en/latest/subsystems/openapi-api-docs.html
Explain how to add Swagger REST API doc coverage in zulip.yaml. Introduce Swagger UI and the Swagger/OpenAPI specification. Explain the structure of zulip.yaml and show examples of different sections of the file. This is a new file in /docs not yet included in the Read the Docs table of contents. Where it should go should be determined as we iterate on the Swagger UI integration and expand REST API doc coverage using it. For more on Swagger UI and how Zulip uses it, see: https://github.com/zulip/zulip/issues/3474 https://github.com/zulip/zulip/pull/3397 With some minor tweaks to advertise this by tabbott.
2017-02-24 03:39:44 +01:00
#
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
openapi: 3.0.1
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
info:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
version: 1.0.0
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
title: Zulip REST API
description: Powerful open source group chat
contact:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
url: https://zulipchat.com
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
servers:
- url: 'https://your.zulip.server/api/v1'
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
# Endpoint definitions
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
paths:
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
/get_stream_id:
get:
description: Get the unique ID of a given stream.
parameters:
- name: stream
in: query
description: The name of the stream to retrieve the ID for.
schema:
type: string
example: Denmark
required: true
security:
- basicAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
stream_id:
type: integer
description: The ID of the given stream.
- example:
{
"msg": "",
"result": "success",
"stream_id": 15
}
'400':
description: Bad request
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream name 'nonexistent'",
"result": "error"
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
/messages:
post:
description: Send a message.
parameters:
- name: type
in: query
description: The type of message to be sent. `private` for a private
message and `stream` for a stream message.
schema:
type: string
enum:
- private
- stream
example: private
required: true
- name: to
in: query
description: The destination stream, or a CSV/JSON-encoded list
containing the usernames (emails) of the recipients.
schema:
type: string
example: aaron@zulip.com, iago@zulip.com
required: true
- name: subject
in: query
description: The topic of the message. Only required if `type` is
`stream`, ignored otherwise. Maximum length of 60 characters.
schema:
type: string
default:
example: Castle
- name: content
in: query
description: The content of the message. Maximum message size of
10000 bytes.
schema:
type: string
example: Hello
required: true
security:
- basicAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
id:
type: integer
description: The ID assigned to the message sent.
- example:
{
"msg": "",
"id": 42,
"result": "success"
}
'400_non_existing_stream':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
stream:
type: string
description: The name of the stream that could not be
found.
- example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 'nonexistent_stream' does not exist",
"result": "error",
"stream": "nonexistent_stream"
}
'400_non_existing_user':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error"
}
docs: Document /get_stream_id API endpoint.
2017-06-25 21:00:55 +02:00
/messages/{message_id}:
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
patch:
description: Edit a message that has already been sent.
parameters:
- name: message_id
in: path
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
description: The ID of the message that you wish to edit/update.
schema:
type: integer
example: 42
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
required: true
- name: subject
in: query
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
description: |
The topic of the message. Only required for stream messages.
Maximum length of 60 characters.
schema:
type: string
default:
example: Castle
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
- name: propagate_mode
in: query
description: |
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
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
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
- name: content
in: query
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
description: |
The content of the message. Maximum message size of 10000 bytes.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schema:
type: string
example: Hello
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
security:
- basicAuth: []
responses:
'200':
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
'400':
description: Bad request.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
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
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
- example:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"code": "BAD_REQUEST",
"msg": "You don't have permission to edit this message",
"result": "error"
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
}
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
/messages/render:
post:
description: Render a message to HTML.
parameters:
- name: content
in: query
description: The content of the message.
schema:
type: string
example: '**foo**'
required: true
security:
- basicAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
rendered:
type: string
description: The rendered HTML.
- example:
{
"msg": "",
"rendered": "<p><strong>foo</strong></p>",
"result": "success"
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
/users/me/{stream_id}/topics:
get:
description: Get all the topics in a specific stream.
parameters:
- name: stream_id
in: path
description: The unique ID of the stream.
schema:
type: integer
example: 42
required: true
security:
- basicAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
topics:
type: array
items:
type: object
properties:
max_id:
description:
The ID of the last message sent to the topic.
type: number
name:
description: The name of the topic.
type: string
- example:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"msg": "",
"result": "success",
"topics": [
{
"max_id": 26,
"name": "Denmark3"
},
{
"max_id": 23,
"name": "Denmark1"
},
{
"max_id": 6,
"name": "Denmark2"
}
]
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error"
}
/users/me/subscriptions:
post:
description: Subscribe one or more users to one or more streams.
parameters:
- name: subscriptions
in: query
description: |
A list of dictionaries, where each dictionary contains key/value
pairs specifying a particular stream to subscribe to.
**Note**: This argument is called `streams` and not `subscriptions`
in our Python API.
schema:
type: string
example: [{"name": "Verona"}]
required: true
- name: invite_only
in: query
description: |
A boolean specifying whether the streams specified in
`subscriptions` are invite-only or not.
schema:
type: boolean
default: false
example: true
- name: announce
in: query
description: |
If `announce` is `True` and one of the streams specified in
`subscriptions` has to be created (i.e. doesn't exist to begin
with), an announcement will be made notifying that a new stream was
created.
schema:
type: boolean
example: true
- name: principals
in: query
description: |
A list of email addresses of the users that will be subscribed to
the streams specified in the `subscriptions` argument. If not
provided, then the requesting user/bot is subscribed.
schema:
type: string
default: []
example: ['ZOE@zulip.com']
- name: authorization_errors_fatal
in: query
description: |
A boolean specifying whether authorization errors (such as when the
requesting user is not authorized to access a private stream) should
be considered fatal or not. When `True`, an authorization error is
reported as such. When set to `False`, the returned JSON payload
indicates that there was an authorization error, but the response is
still considered a successful one.
schema:
type: boolean
default: true
example: false
security:
- basicAuth: []
responses:
'200_without_principals':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {
"iago@zulip.com": [
"new stream"
]
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
'200_already_subscribed':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {
"newbie@zulip.com": [
"new stream"
]
},
"msg": "",
"result": "success",
"subscribed": {}
}
'400_unauthorized_errors_fatal_true':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error"
}
'400_unauthorized_errors_fatal_false':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": [
"private_stream"
]
}
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
/streams:
get:
description: Get all streams that the user has access to.
parameters:
- name: include_public
in: query
description: Include all public streams.
schema:
type: boolean
default : true
example: false
- name: include_subscribed
in: query
description: Include all streams that the user is subscribed to.
schema:
type: boolean
default : true
example: false
- name: include_all_active
in: query
description: Include all active streams. The user must have
administrative privileges to use this parameter.
schema:
type: boolean
default : false
example: true
- name: include_default
in: query
description: Include all default streams for the user's realm.
schema:
type: boolean
default : false
example: true
security:
- basicAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
streams:
type: array
items:
type: object
description: A list of `stream` objects, which contain a
`description`, a `name`, their `stream_id` and whether
they are `invite_only` or not.
- example:
{
"msg": "",
"result": "success",
"streams": [
{
"description": "A Scandinavian country",
"invite_only": false,
"name": "Denmark",
"stream_id": 1
},
{
"description": "Yet another Italian city",
"invite_only": false,
"name": "Rome",
"stream_id": 2
},
{
"description": "Located in the United Kingdom",
"invite_only": false,
"name": "Scotland",
"stream_id": 3
},
{
"description": "A northeastern Italian city",
"invite_only": false,
"name": "Venice",
"stream_id": 4
},
{
"description": "A city in Italy",
"invite_only": false,
"name": "Verona",
"stream_id": 5
},
{
"description": "New stream for testing",
"invite_only": false,
"name": "new stream",
"stream_id": 6
}
]
}
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error"
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
components:
#######################
# Security definitions
#######################
securitySchemes:
BasicAuth:
type: http
scheme: basic
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
description: |
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
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.
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schemas:
JsonResponse:
type: object
properties:
docs: Amend definitions of JSON responses.
2017-06-25 17:52:59 +02:00
result:
docs: Fix JsonSuccess and JsonError models.
2017-05-24 05:22:50 +02:00
type: string
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- success
msg:
type: string
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
- example:
{
"msg": "",
"result": "success"
}
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonError:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- error
msg:
type: string
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
CodedError:
allOf:
- $ref: '#/components/schemas/JsonError'
- properties:
code:
type: string
description: A string that identifies the error.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
AddSubscriptionsResponse:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
subscribed:
type: object
description: |
A dictionary where the key is the email address of the user/bot
and the value is a list of the names of the streams that were
subscribed to as a result of the query.
already_subscribed:
type: object
description: |
A dictionary where the key is the email address of the user/bot
and the value is a list of the names of the streams that the
user/bot is already subscribed to.
unauthorized:
type: array
items:
type: string
description: |
A list of names of streams that the requesting user/bot was not
authorized to subscribe to.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
###################
# Shared responses
###################
responses:
SimpleSuccess:
description: Success
docs: Document /messages API endpoint.
2017-05-24 01:54:20 +02:00
content:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'