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

1136 lines
30 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 IS DEPRECATED! Please refer to zulip.yaml, which contains the new
# specification (using OpenAPI 3.0).
# This file contains the Swagger UI configuration and API definitions
# for the Zulip REST API.
#
# For details on the Swagger/OpenAPI specification, see http://swagger.io/specification
#
# Our own documentation lives at
#
docs: Extract a Writing Documentation top-level section. This should make this easier to find, and also makes "Subsystems" a bit smaller of a catch-all.
2019-05-30 00:39:50 +02:00
# https://zulip.readthedocs.io/en/latest/documentation/openapi.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
#
# Basic Swagger UI info
swagger: '2.0'
info:
version: '1.0.0'
title: Zulip REST API
description: Powerful open source group chat
contact:
url: https://zulip.org/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
# Backend host to use for API examples.
# This defaults to the Swagger UI host,
# which in this case is also the Zulip host.
#host: 10.2.3.4:9991
# The base configuration for this API
basePath: /api/v1
schemes:
- http
- https
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
######################
# Endpoint definitions
paths:
/events:
get:
description: Get new events from an events queue
operationId: getEvents
parameters:
- name: queue_id
in: query
description: The ID of a queue that you registered via `POST /api/v1/register`.
required: true
type: string
- name: last_event_id
in: query
description: |
The highest event ID in this queue that you've received and
wish to acknowledge. See the code for `call_on_each_event` in
the zulip Python module for an example implementation of
correctly processing each event exactly once.
required: true
type: string
- name: dont_block
in: query
description: |
Set to `true` if the client is requesting a
nonblocking reply. If not specified, the request will block
until either a new event is available or a few minutes have
passed, in which case the server will send the client a
heartbeat event.
required: false
type: string
security:
- basicAuth: []
responses:
'200':
description: |
* `events`: An array (possibly zero-length if `dont_block` is
set) of events with IDs newer than `last_event_id`.
Event IDs are guaranted to be increasing, but they are not
guaranteed to be consecutive.
schema:
$ref: '#/definitions/EventsResponse'
/fetch_api_key:
post:
description: |
Gather a token bound to a user account, to identify and
authenticate them when making operations in the API.
This token must be used as the password in the rest of the
endpoints that require Basic authentication.
operationId: zerver.views.auth.api_fetch_api_key
parameters:
- name: username
in: formData
description: The email address for the user that owns the API key.
required: true
type: string
- name: password
in: formData
description: The password for the account of the API key's owner.
required: true
type: string
responses:
'200':
description: Success.
schema:
allOf:
- $ref: '#/definitions/JsonSuccess'
- required:
- api_key
- email
- properties:
api_key:
type: string
example: c2hvdWxuJ3QgdSBiZSB3b3JraW5nPzsp
email:
description: |
The email address for the user that owns the API
key.
type: string
example: iago@zulip.com
msg:
enum:
- ''
/get_stream_id:
get:
description: Fetch a stream's ID from its name.
operationId: zerver.views.streams.json_get_stream_id
parameters:
- name: stream
in: query
description: The name of the stream whose ID to fetch.
required: true
type: string
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
allOf:
- $ref: '#/definitions/JsonSuccess'
- properties:
stream_id:
type: integer
example: 42
msg:
enum:
- ''
'400':
description: Bad request.
schema:
allOf:
- $ref: '#/definitions/JsonError'
- properties:
msg:
enum:
- Invalid stream name '<stream>'
/messages:
post:
description: Send a message
operationId: zerver.views.messages.send_message_backend
parameters:
- name: type
in: formData
description: One of {`private`, `stream`}
required: true
type: string
- name: content
in: formData
description: The content of the message. Maximum message size of 10000 bytes.
required: true
type: string
- name: to
in: formData
description: |
In the case of a stream message, a string identifying the
stream. In the case of a private message, a JSON-encoded
list containing the usernames of the recipients.
required: true
type: string
- name: subject
in: formData
description: |
The topic for the message (only required if type is `stream`).
Maximum length of 60 characters.
required: false
type: string
security:
- basicAuth: []
responses:
'200':
description: |
* `msg`:
* `result`:
* `id`: The ID of the newly created message.
schema:
$ref: '#/definitions/MessageResponse'
/messages/{message_id}:
patch:
description: Edit a message that has already been sent.
parameters:
- name: message_id
in: path
description: ID of the message to be edited.
type: integer
required: true
- name: subject
in: query
description: Message's new topic.
type: string
- 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.
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
- name: content
in: query
description: Message's new body.
type: string
security:
- basicAuth: []
responses:
'200':
description: Success
schema:
$ref: '#/definitions/JsonSuccess'
'400':
description: Bad request.
schema:
allOf:
- $ref: '#/definitions/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
/register:
post:
description: Register a queue to receive new messages
operationId: registerQueue
parameters:
- name: event_types
in: formData
description: |
A JSON-encoded array indicating which types of
events you're interested in. Values that you might find
useful include:
`message` (messages),
`subscriptions` (changes in your subscriptions),
`realm_user` (changes in the list of users in your realm), and
`pointer` (changes in your pointer).
If you do not specify this argument, you will receive all
events, and have to filter out the events not relevant to
your client in your client code. For most applications, one
is only interested in messages, so one specifies:
`event_types=["message"]`
required: false
type: string
- name: apply_markdown
in: formData
description: |
Set to `true` if you would like the content to
be rendered in HTML format (by default, the API returns the
raw text that the user entered.)
required: false
type: string
security:
- basicAuth: []
responses:
'200':
description: |
## These values will always be in the response:
* `msg`:
* `result`:
* `queue_id`: The ID of the queue that has been allocated for
your client.
* `last_event_id`: The initial value of the `last_event_id`
value to pass to `GET /api/v1/events`.
## The following values may be returned, depending on the value
of `event_types` provided:
* `max_message_id`:
* `pointer`:
* `realm_users`:
* `alert_words`:
* `attachments`:
* `default_language`:
* `enable_desktop_notifications`:
* `enable_digest_emails`:
* `enable_offline_email_notifications`:
* `enable_offline_push_notifications`:
* `enable_online_push_notifications`:
* `enable_sounds`:
* `enable_stream_desktop_notifications`:
models: Rename notification to `enable_stream_audible_notifications`. Rename notification property `enable_stream_sounds` to `enable_stream_audible_notifications` to match with other notification property patterns. Fixes part of #12304
2019-06-11 08:47:49 +02:00
* `enable_stream_audible_notifications`:
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
* `left_side_userlist`:
* `muted_topics`:
* `never_subscribed`:
* `presences`:
* `realm_add_emoji_by_admins_only`:
* `realm_allow_message_deleting`:
* `realm_allow_message_editing`:
* `realm_authentication_methods`:
* `realm_bots`:
settings: Migrate to create_stream_policy structure. This commit replaces the `create_stream_by_admins_only` setting with a new `create_stream_policy` setting, which mirroring the structure of the existing `invite_to_stream_policy`. This is important preparation for migrating the waiting period feature to be its own independent setting. Fixes #12236.
2019-05-06 16:34:31 +02:00
* `realm_create_stream_policy`:
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
settings: Create an explicit invite_to_stream_policy setting. This commit creates a new organization setting that determines whether a user can invite other users to streams. Previously this was linked to the waiting period threshold, but this was both not documented and overly limiting. With significant tweaks by tabbott to change the database model to not involve two threshhold fields, edit the tests, etc. This requires follow-up work to make the create stream policy setting work how this code implies it should. Fixes #12042.
2019-04-08 19:23:00 +02:00
* `realm_invite_to_stream_policy`:
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
* `realm_default_language`:
* `realm_default_streams`:
* `realm_domain`:
* `realm_domains`:
* `realm_emoji`:
* `realm_filters`:
* `realm_invite_by_admins_only`:
* `realm_invite_required`:
* `realm_message_content_edit_limit_seconds`:
* `realm_message_content_delete_limit_seconds`:
* `realm_name`:
models: Rename Realm.restricted_to_domain field. This renames Realm.restricted_to_domain field to emails_restricted_to_domains, for greater clarity as to what it does just from seeing the setting name, without having to look it up. Fixes part of #10042.
2018-07-27 23:26:29 +02:00
* `realm_emails_restricted_to_domains`:
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
* `realm_users`:
* `realm_waiting_period_threshold`:
* `streams`:
* `twenty_four_hour_time`:
* `unsubscribed`:
schema:
$ref: '#/definitions/RegisterResponse'
/streams:
get:
description: Gets a list of streams available to a user on the server.
operationId: zerver.views.streams.get_streams_backend
security:
- basicAuth: []
parameters:
- name: include_public
in: query
description: |
Set to `false` if the response should not include
public streams.
type: string
default: true
- name: include_all_active
in: query
description: |
Set to `true` if the response should include all active
streams, including private ones. This requires
API super user access.
type: string
default: false
- name: include_default
in: query
description: |
Set to `true` if the response should include all the
streams to which new users are subscribed by default.
type: string
default: false
- name: include_subscribed
in: query
description: |
Set to `false` if response should not include streams
where user is considered subscribed.
type: string
default: true
responses:
'200':
description: Success.
schema:
allOf:
- $ref: '#/definitions/JsonSuccess'
- description: |
`stream` is an array (that can be zero-length
depending on the parameters set) of available
streams for the authenticated user.
- properties:
streams:
type: array
items:
$ref: '#/definitions/stream'
/streams/{stream_id}:
patch:
description: Update a stream's name, description or privacy setting.
operationId: zerver.views.streams.update_stream_backend
parameters:
- name: stream_id
in: path
description: The ID of the stream to modify.
required: true
type: integer
- name: new_name
in: formData
description: |
New name for the stream.
Must be a valid JSON string (enclosed in double quotes and
special characters escaped with backslashes).
type: string
- name: description
in: formData
description: |
New description for the stream.
Must be a valid JSON string (enclosed in double quotes and
special characters escaped with backslashes).
type: string
- name: is_private
in: formData
description: New privacy setting for the stream.
type: boolean
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/JsonSuccess'
'400':
description: Bad request.
schema:
allOf:
- $ref: '#/definitions/JsonError'
- properties:
msg:
enum:
- Argument "new_name" is not valid JSON.
- Argument "description" is not valid JSON.
- '"new_name" is not a string'
- '"description" is not a string'
- '"is_private" is not a boolean'
- Stream already has that name!
# API_FIXME: There's no error for when the stream already has
# the specified description or privacy setting.
delete:
description: |
Delete a stream.
The result is the stream deactivation; its messages will
remain in the database, but they won't be recoverable
through the API.
operationId: zerver.views.streams.deactivate_stream_backend
parameters:
- name: stream_id
in: path
description: The ID of the stream to delete.
required: true
type: integer
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/JsonSuccess'
'400':
description: Bad request.
schema:
allOf:
- $ref: '#/definitions/JsonError'
- properties:
msg:
enum:
- 'Invalid stream id'
/users/{user}/presence:
get:
description: Get presence data for another user.
operationId: getPresence
parameters:
- name: user
in: path
description: Enter email address
required: true
type: string
security:
- basicAuth: []
responses:
'200':
description: The response from a successful call
schema:
type: object
required:
- msg
- result
- presence
properties:
msg:
type: string
result:
type: string
presence:
type: array
/users/me/subscriptions:
get:
description: List streams subscription data for the current user.
operationId: zerver.views.streams.list_subscriptions_backend
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
type: object
required:
- msg
- result
- subscriptions
properties:
msg:
type: string
result:
type: string
subscriptions:
type: array
items:
$ref: '#/definitions/stream'
post:
description: Bulk adds streams subscription data for the current user.
operationId: zerver.views.streams.add_subscriptions_backend
parameters:
- name: subscriptions
in: formData
description: |
Serialized JSON string, with the details of the streams
the user is subscribing to.
```
[{
"name":string, (required)
"invite-only":bool (optional)
}]
```
required: true
type: string
- name: invite_only
in: formData
type: boolean
default: false
- name: announce
in: formData
type: boolean
default: false
- name: authorization_errors_fatal
in: formData
type: boolean
default: true
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
type: object
required:
- msg
- already_subscribed
- result
- subscribed
properties:
msg:
type: string
already_subscribed:
type: object
properties:
subscriber:
type: array
items:
type: string
result:
type: string
subscribed:
type: object
properties:
subscriber:
type: array
items:
type: string
patch:
description: |
Bulk modifies (add or delete) streams subscription data
for the current user.
operationId: zerver.views.streams.update_subscriptions_backend
parameters:
- name: delete
in: formData
description: |
Serialized JSON list of streams to delete. See the
`subscriptions` parameter in the POST method for
details about the format.
type: string
- name: add
in: formData
description: |
Serialized JSON list of streams to add. See the
`subscriptions` parameter in the POST method for
details about the format.
type: string
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
type: object
required:
- subscribed
- not_subscribed
- result
- msg
- already_subscribed
- removed
properties:
subscribed:
type: object
properties:
subscriber:
type: array
items:
type: string
not_subscribed:
type: array
items:
type: string
result:
type: string
msg:
type: string
already_subscribed:
type: object
properties:
subscriber:
type: array
items:
type: string
removed:
type: array
items:
type: string
delete:
description: |
Bulk deletes streams subscription data for the current
user.
operationId: zerver.views.streams.remove_subscriptions_backend
parameters:
- name: subscriptions
in: formData
description: |
Serialized JSON list of streams to unsubscribe from.
See the `subscriptions` parameter in the POST method
for details about the format.
required: true
type: string
security:
- basicAuth: []
responses:
'200':
description: Success.
schema:
type: object
required:
- msg
- removed
- not_subscribed
- result
properties:
msg:
type: string
removed:
type: array
items:
type: string
not_subscribed:
type: array
items:
type: string
result:
type: string
/user_uploads:
post:
description: Upload a file, and print the corresponding URI.
operationId: userUploads
consumes:
- multipart/form-data
parameters:
- name: file
in: formData
description: File to be uploaded
type: file
required: true
security:
- basicAuth: []
responses:
'200':
description: Success
schema:
type: object
required:
- msg
- result
- uri
properties:
msg:
type: string
result:
type: string
uri:
type: string
#######################
# Security definitions
#######################
securityDefinitions:
basicAuth:
type: 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.
####################
# Shared definitions
definitions:
JsonResponse:
type: object
properties:
result:
type: string
JsonSuccess:
allOf:
- $ref: '#/definitions/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- success
msg:
type: string
JsonError:
allOf:
- $ref: '#/definitions/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- error
msg:
type: string
# /register
RegisterResponse:
type: object
required:
- msg
- result
- queue_id
- last_event_id
properties:
msg:
type: string
result:
type: string
queue_id:
type: string
last_event_id:
type: integer
format: int64
alert_words:
type: string
attachments:
type: string
default_language:
type: string
enable_desktop_notifications:
type: boolean
enable_digest_emails:
type: boolean
enable_offline_email_notifications:
type: boolean
enable_offline_push_notifications:
type: boolean
enable_online_push_notifications:
type: boolean
enable_sounds:
type: boolean
enable_stream_desktop_notifications:
type: boolean
models: Rename notification to `enable_stream_audible_notifications`. Rename notification property `enable_stream_sounds` to `enable_stream_audible_notifications` to match with other notification property patterns. Fixes part of #12304
2019-06-11 08:47:49 +02:00
enable_stream_audible_notifications:
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
type: boolean
left_side_userlist:
type: boolean
max_message_id:
type: integer
format: int64
muted_topics:
type: string
never_subscribed:
type: array
items:
$ref: '#/definitions/stream'
pointer:
type: integer
format: int64
presences:
type: string
realm_add_emoji_by_admins_only:
type: boolean
realm_allow_message_deleting:
type: boolean
realm_allow_message_editing:
type: boolean
realm_authentication_methods:
type: string
realm_bots:
type: string
settings: Migrate to create_stream_policy structure. This commit replaces the `create_stream_by_admins_only` setting with a new `create_stream_policy` setting, which mirroring the structure of the existing `invite_to_stream_policy`. This is important preparation for migrating the waiting period feature to be its own independent setting. Fixes #12236.
2019-05-06 16:34:31 +02:00
realm_create_stream_policy:
type: int64
settings: Create an explicit invite_to_stream_policy setting. This commit creates a new organization setting that determines whether a user can invite other users to streams. Previously this was linked to the waiting period threshold, but this was both not documented and overly limiting. With significant tweaks by tabbott to change the database model to not involve two threshhold fields, edit the tests, etc. This requires follow-up work to make the create stream policy setting work how this code implies it should. Fixes #12042.
2019-04-08 19:23:00 +02:00
realm_invite_to_stream_policy:
type: int64
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
realm_default_language:
type: string
realm_default_streams:
type: array
items:
$ref: '#/definitions/stream'
realm_domain:
type: string
realm_domains:
type: string
realm_emoji:
type: string
realm_filters:
type: string
realm_invite_by_admins_only:
type: boolean
realm_invite_required:
type: boolean
realm_message_content_edit_limit_seconds:
type: integer
format: int64
realm_message_content_delete_limit_seconds:
type: integer
format: int64
realm_name:
type: string
models: Rename Realm.restricted_to_domain field. This renames Realm.restricted_to_domain field to emails_restricted_to_domains, for greater clarity as to what it does just from seeing the setting name, without having to look it up. Fixes part of #10042.
2018-07-27 23:26:29 +02:00
realm_emails_restricted_to_domains:
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
type: boolean
realm_users:
type: array
items:
$ref: '#/definitions/user'
realm_waiting_period_threshold:
type: integer
format: int64
streams:
type: array
items:
$ref: '#/definitions/stream'
twenty_four_hour_time:
type: boolean
unsubscribed:
type: string
# /messages GET
MessagesResponse:
type: object
required:
- msg
- result
- messages
properties:
msg:
type: string
result:
type: string
messages:
type: array
items:
$ref: '#/definitions/message'
# /messages POST
MessageResponse:
type: object
required:
- msg
- result
- id
properties:
msg:
type: string
result:
type: string
id:
type: integer
format: int64
# /events
EventsResponse:
type: object
required:
- msg
- result
- events
properties:
msg:
type: string
result:
type: string
events:
type: array
items:
$ref: '#/definitions/event'
#####
# definitions used by /register
#
#alert_words
#attachments
#muted_topics
#presences
#realm_authentication_methods
#realm_bots
#realm_domains
#realm_emoji
#realm_filters
#subscriptions
#unsubscribed
message:
type: object
required:
- reactions
- recipient_id
- content_type
- timestamp
- display_recipient
- sender_id
- sender_full_name
- client
- content
- stream_id
- avatar_url
- flags
- sender_email
- subject_links
- sender_realm_str
- subject
- type
- id
- sender_short_name
properties:
reactions:
# TODO: Create a full definition for reactions
type: object
recipient_id:
type: integer
content_type:
type: string
timestamp:
type: integer
display_recipient:
type: array
description: |
If the recipient is a stream, this will be a `string`
(not an `array`), with the stream's name.
items:
type: object
# TODO: Create a definition for this type of user (doesn't match
# the already existing ones)
sender_id:
type: integer
sender_full_name:
type: string
client:
type: string
content:
type: string
stream_id:
type: integer
avatar_url:
type: string
flags:
type: array
items:
type: string
sender_email:
type: string
subject_links:
type: array
items:
type: string
sender_realm_str:
type: string
subject:
type: string
type:
type: string
id:
type: integer
sender_short_name:
type: string
stream:
type: object
required:
- stream_id
- description
- name
- invite_only
properties:
stream_id:
type: integer
format: int64
description:
type: string
name:
type: string
invite_only:
type: boolean
user:
type: object
required:
- is_admin
- user_id
- email
- full_name
- is_bot
properties:
is_admin:
type: boolean
user_id:
type: integer
format: int64
email:
type: string
full_name:
type: string
is_bot:
type: boolean
#####
# definitions used by /events
#
event:
type: object
required:
- type
- id
properties:
type:
type: string
id:
type: integer
format: int64