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

api docs: Minor formatting improvements.

This commit is contained in:
Yago González 2018-06-21 02:03:15 +02:00 committed by Tim Abbott
parent 90e3b8d808
commit d45fac0327
1 changed files with 89 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
zerver/openapi/zulip.yaml
View File

@ -18,7 +18,7 @@ info:
name: Apache 2.0 name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html url: https://www.apache.org/licenses/LICENSE-2.0.html
servers: servers:
- url: 'https://your.zulip.server/api/v1' - url: 'https://your.zulip.server/api/v1'
####################### #######################
# Endpoint definitions # Endpoint definitions
@ -61,7 +61,7 @@ paths:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -134,7 +134,7 @@ paths:
"result": "success" "result": "success"
} }
'400': '400':
description: Bad request description: Bad request.
content: content:
application/json: application/json:
schema: schema:
@ -147,7 +147,7 @@ paths:
description: The ID of a queue that you registered via description: The ID of a queue that you registered via
`POST /api/v1/register`(see [Register a queue](/api/register-queue). `POST /api/v1/register`(see [Register a queue](/api/register-queue).
schema: schema:
type: string type: string
example: 1375801870:2942 example: 1375801870:2942
required: true required: true
security: security:
@ -173,14 +173,14 @@ paths:
in: query in: query
description: The name of the stream to retrieve the ID for. description: The name of the stream to retrieve the ID for.
schema: schema:
type: string type: string
example: Denmark example: Denmark
required: true required: true
security: security:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -197,7 +197,7 @@ paths:
"stream_id": 15 "stream_id": 15
} }
'400': '400':
description: Bad request description: Bad request.
content: content:
application/json: application/json:
schema: schema:
@ -220,8 +220,8 @@ paths:
schema: schema:
type: string type: string
enum: enum:
- private - private
- stream - stream
example: private example: private
required: true required: true
- name: to - name: to
@ -252,7 +252,7 @@ paths:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -313,19 +313,17 @@ paths:
required: true required: true
- name: subject - name: subject
in: query in: query
description: | description: The topic of the message. Only required for stream
The topic of the message. Only required for stream messages. messages. Maximum length of 60 characters.
Maximum length of 60 characters.
schema: schema:
type: string type: string
default: default:
example: Castle example: Castle
- name: propagate_mode - name: propagate_mode
in: query in: query
description: | description: "Which message(s) should be edited: just the one
Which message(s) should be edited: just the one indicated in indicated in `message_id`, messages in the same topic that had been
`message_id`, messages in the same topic that had been sent after sent after this one, or all of them."
this one, or all of them.
schema: schema:
type: string type: string
enum: enum:
@ -336,8 +334,8 @@ paths:
example: change_all example: change_all
- name: content - name: content
in: query in: query
description: | description: The content of the message. Maximum message size of 10000
The content of the message. Maximum message size of 10000 bytes. bytes.
schema: schema:
type: string type: string
example: Hello example: Hello
@ -345,7 +343,7 @@ paths:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -375,18 +373,18 @@ paths:
post: post:
description: Render a message to HTML. description: Render a message to HTML.
parameters: parameters:
- name: content - name: content
in: query in: query
description: The content of the message. description: The content of the message.
schema: schema:
type: string type: string
example: '**foo**' example: '**foo**'
required: true required: true
security: security:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -442,14 +440,14 @@ paths:
description: The `client_gravatar` field is set to `true` if clients description: The `client_gravatar` field is set to `true` if clients
can compute their own gravatars. can compute their own gravatars.
schema: schema:
type: boolean type: boolean
default : false default: false
example: true example: true
security: security:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -505,28 +503,28 @@ paths:
in: query in: query
description: The email address of the new user. description: The email address of the new user.
schema: schema:
type: string type: string
example: newbie@zulip.com example: newbie@zulip.com
required: true required: true
- name: password - name: password
in: query in: query
description: The password of the new user. description: The password of the new user.
schema: schema:
type: string type: string
example: abdec@7982 example: abdec@7982
required: true required: true
- name: full_name - name: full_name
in: query in: query
description: The full name of the new user. description: The full name of the new user.
schema: schema:
type: string type: string
example: John Smith example: John Smith
required: true required: true
- name: short_name - name: short_name
in: query in: query
description: The short name of the new user. description: The short name of the new user.
schema: schema:
type: string type: string
example: jsmith example: jsmith
required: true required: true
security: security:
@ -565,7 +563,7 @@ paths:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -622,19 +620,17 @@ paths:
parameters: parameters:
- name: subscriptions - name: subscriptions
in: query in: query
description: | description: "A list of dictionaries, where each dictionary contains
A list of dictionaries, where each dictionary contains key/value key/value pairs specifying a particular stream to subscribe to.
pairs specifying a particular stream to subscribe to.
**Note**: This argument is called `streams` and not `subscriptions` **Note**: This argument is called `streams` and not `subscriptions`
in our Python API. in our Python API."
schema: schema:
type: string type: array
example: [{"name": "Verona"}] example: [{"name": "Verona"}]
required: true required: true
- name: invite_only - name: invite_only
in: query in: query
description: | description: A boolean specifying whether the streams specified in
A boolean specifying whether the streams specified in
`subscriptions` are invite-only or not. `subscriptions` are invite-only or not.
schema: schema:
type: boolean type: boolean
@ -642,9 +638,8 @@ paths:
example: true example: true
- name: announce - name: announce
in: query in: query
description: | description: If `announce` is `True` and one of the streams specified
If `announce` is `True` and one of the streams specified in in `subscriptions` has to be created (i.e. doesn't exist to begin
`subscriptions` has to be created (i.e. doesn't exist to begin
with), an announcement will be made notifying that a new stream was with), an announcement will be made notifying that a new stream was
created. created.
schema: schema:
@ -652,23 +647,21 @@ paths:
example: true example: true
- name: principals - name: principals
in: query in: query
description: | description: A list of email addresses of the users that will be
A list of email addresses of the users that will be subscribed to subscribed to the streams specified in the `subscriptions` argument.
the streams specified in the `subscriptions` argument. If not If not provided, then the requesting user/bot is subscribed.
provided, then the requesting user/bot is subscribed.
schema: schema:
type: string type: array
default: [] default: []
example: ['ZOE@zulip.com'] example: ['ZOE@zulip.com']
- name: authorization_errors_fatal - name: authorization_errors_fatal
in: query in: query
description: | description: A boolean specifying whether authorization errors (such
A boolean specifying whether authorization errors (such as when the as when the requesting user is not authorized to access a private
requesting user is not authorized to access a private stream) should stream) should be considered fatal or not. When `True`, an
be considered fatal or not. When `True`, an authorization error is authorization error is reported as such. When set to `False`, the
reported as such. When set to `False`, the returned JSON payload returned JSON payload indicates that there was an authorization
indicates that there was an authorization error, but the response is error, but the response is still considered a successful one.
still considered a successful one.
schema: schema:
type: boolean type: boolean
default: true default: true
@ -677,7 +670,7 @@ paths:
- basicAuth: [] - basicAuth: []
responses: responses:
'200_without_principals': '200_without_principals':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -695,7 +688,7 @@ paths:
} }
} }
'200_already_subscribed': '200_already_subscribed':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -713,7 +706,7 @@ paths:
"subscribed": {} "subscribed": {}
} }
'400_unauthorized_errors_fatal_true': '400_unauthorized_errors_fatal_true':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -725,7 +718,7 @@ paths:
"result": "error" "result": "error"
} }
'400_unauthorized_errors_fatal_false': '400_unauthorized_errors_fatal_false':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -832,16 +825,16 @@ paths:
rendered in HTML format (by default, the API returns the raw text rendered in HTML format (by default, the API returns the raw text
that the user entered) that the user entered)
schema: schema:
type: boolean type: boolean
default : false default: false
example: true example: true
- name: client_gravatar - name: client_gravatar
in: query in: query
description: The `client_gravatar` field is set to `true` if clients description: The `client_gravatar` field is set to `true` if clients
can compute their own gravatars. can compute their own gravatars.
schema: schema:
type: boolean type: boolean
default : false default: false
example: true example: true
- name: event_types - name: event_types
in: query in: query
@ -857,23 +850,23 @@ paths:
your client code. For most applications, one is only interested in your client code. For most applications, one is only interested in
messages, so one specifies: `event_types=['message']`" messages, so one specifies: `event_types=['message']`"
schema: schema:
type: string type: string
example: event_types=['message'] example: event_types=['message']
- name: all_public_streams - name: all_public_streams
in: query in: query
description: Set to `True` if you would like to receive events that description: Set to `True` if you would like to receive events that
occur within all public streams. occur within all public streams.
schema: schema:
type: boolean type: boolean
default: false default: false
example: true example: true
- name: include_subscribers - name: include_subscribers
in: query in: query
description: Set to `True` if you would like to receive events that description: Set to `True` if you would like to receive events that
include the subscribers for each stream. include the subscribers for each stream.
schema: schema:
type: boolean type: boolean
default : false default: false
example: true example: true
- name: fetch_event_types - name: fetch_event_types
in: query in: query
@ -882,7 +875,7 @@ paths:
`fetch_event_types` is not provided, `event_types` is used and if `fetch_event_types` is not provided, `event_types` is used and if
`event_types` is not provided, this argument defaults to `None`. `event_types` is not provided, this argument defaults to `None`.
schema: schema:
type: string type: string
example: event_types=['message'] example: event_types=['message']
- name: narrow - name: narrow
in: query in: query
@ -892,14 +885,14 @@ paths:
`narrow=['stream', 'Denmark']`. Another example is `narrow=['stream', 'Denmark']`. Another example is
`narrow=['is', 'private']` for private messages. `narrow=['is', 'private']` for private messages.
schema: schema:
type: string type: string
default : narrow=[] default: narrow=[]
example: narrow=['stream', 'Denmark'] example: narrow=['stream', 'Denmark']
security: security:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -942,36 +935,36 @@ paths:
in: query in: query
description: Include all public streams. description: Include all public streams.
schema: schema:
type: boolean type: boolean
default : true default: true
example: false example: false
- name: include_subscribed - name: include_subscribed
in: query in: query
description: Include all streams that the user is subscribed to. description: Include all streams that the user is subscribed to.
schema: schema:
type: boolean type: boolean
default : true default: true
example: false example: false
- name: include_all_active - name: include_all_active
in: query in: query
description: Include all active streams. The user must have description: Include all active streams. The user must have
administrative privileges to use this parameter. administrative privileges to use this parameter.
schema: schema:
type: boolean type: boolean
default : false default: false
example: true example: true
- name: include_default - name: include_default
in: query in: query
description: Include all default streams for the user's realm. description: Include all default streams for the user's realm.
schema: schema:
type: boolean type: boolean
default : false default: false
example: true example: true
security: security:
- basicAuth: [] - basicAuth: []
responses: responses:
'200': '200':
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema:
@ -1050,10 +1043,9 @@ components:
BasicAuth: BasicAuth:
type: http type: http
scheme: basic scheme: basic
description: | description: Basic authentication, with the user's email as the
Basic authentication, with the user's email as the username, and the username, and the API key as the password. The API key can be fetched
API key as the password. The API key can be fetched using the using the `/fetch_api_key` or `/dev_fetch_api_key` endpoints.
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
schemas: schemas:
JsonResponse: JsonResponse:
@ -1117,30 +1109,27 @@ components:
- properties: - properties:
subscribed: subscribed:
type: object type: object
description: | description: A dictionary where the key is the email address of
A dictionary where the key is the email address of the user/bot the user/bot and the value is a list of the names of the streams
and the value is a list of the names of the streams that were that were subscribed to as a result of the query.
subscribed to as a result of the query.
already_subscribed: already_subscribed:
type: object type: object
description: | description: A dictionary where the key is the email address of
A dictionary where the key is the email address of the user/bot the user/bot and the value is a list of the names of the streams
and the value is a list of the names of the streams that the that the user/bot is already subscribed to.
user/bot is already subscribed to.
unauthorized: unauthorized:
type: array type: array
items: items:
type: string type: string
description: | description: A list of names of streams that the requesting
A list of names of streams that the requesting user/bot was not user/bot was not authorized to subscribe to.
authorized to subscribe to.
################### ###################
# Shared responses # Shared responses
################### ###################
responses: responses:
SimpleSuccess: SimpleSuccess:
description: Success description: Success.
content: content:
application/json: application/json:
schema: schema: