mirror of https://github.com/zulip/zulip.git
615 lines
15 KiB
YAML
615 lines
15 KiB
YAML
# THIS FILE IS DEPRECATED! Please refer to zulip.yaml, which contains the new
|
|
# specification (using OpenAPI 3.0).
|
|
#
|
|
# The current contents of this file should be reviewed and migrated to the new
|
|
# zulip.yaml.
|
|
|
|
# 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
|
|
#
|
|
# https://zulip.readthedocs.io/en/latest/documentation/openapi.html
|
|
#
|
|
# 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:
|
|
|
|
/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:
|
|
- ''
|
|
|
|
/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/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'
|
|
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
|
|
|
|
#######################
|
|
# 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
|
|
enable_stream_audible_notifications:
|
|
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
|
|
realm_create_stream_policy:
|
|
type: int64
|
|
realm_invite_to_stream_policy:
|
|
type: int64
|
|
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
|
|
realm_emails_restricted_to_domains:
|
|
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
|