feat: Switch from Redoc to Stoplight Elements for API documentation (#30591)
Этот коммит содержится в:
Eva Sarafianou
коммит произвёл
GitHub
GitHub
родитель
e00cccd33f
Коммит
b548a8f336
5
.github/workflows/api.yml
поставляемый
5
.github/workflows/api.yml
поставляемый
@@ -28,8 +28,3 @@ jobs:
|
|||||||
|
|
||||||
- name: Run build
|
- name: Run build
|
||||||
run: make build
|
run: make build
|
||||||
|
|
||||||
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
|
|
||||||
with:
|
|
||||||
name: mattermost-api-reference
|
|
||||||
path: api/v4/html
|
|
||||||
|
|||||||
@@ -66,7 +66,7 @@ build-v4: node_modules playbooks
|
|||||||
cd server && go run . $(V4_YAML)
|
cd server && go run . $(V4_YAML)
|
||||||
|
|
||||||
@node_modules/.bin/swagger-cli validate $(V4_YAML)
|
@node_modules/.bin/swagger-cli validate $(V4_YAML)
|
||||||
@node_modules/.bin/redocly -t ./v4/html/ssr_template.hbs build-docs ./v4/html/static/mattermost-openapi-v4.yaml -o ./v4/html/index.html
|
@cp ./v4/html/ssr_template.hbs ./v4/html/index.html
|
||||||
@echo Complete
|
@echo Complete
|
||||||
|
|
||||||
node_modules: package.json $(wildcard package-lock.json)
|
node_modules: package.json $(wildcard package-lock.json)
|
||||||
@@ -76,9 +76,8 @@ node_modules: package.json $(wildcard package-lock.json)
|
|||||||
touch $@
|
touch $@
|
||||||
|
|
||||||
run:
|
run:
|
||||||
@echo Starting redoc server
|
@echo Starting local server
|
||||||
|
python3 -m http.server 8080 --directory ./v4/html
|
||||||
@node_modules/.bin/redocly preview-docs ./v4/html/static/mattermost-openapi-v4.yaml
|
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
@echo Cleaning
|
@echo Cleaning
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Mattermost API Documentation
|
# Mattermost API Documentation
|
||||||
|
|
||||||
This repository holds the API reference available at [https://api.mattermost.com](https://api.mattermost.com).
|
This repository holds the API reference documentation for Mattermost available at [https://developers.mattermost.com/api-reference](https://developers.mattermost.com/api-reference).
|
||||||
|
|
||||||
The Mattermost API reference uses the [OpenAPI standard](https://openapis.org/) and the [ReDoc document generator](https://github.com/Rebilly/ReDoc).
|
The Mattermost API reference uses the [OpenAPI standard](https://openapis.org/) and the [ReDoc document generator](https://github.com/Rebilly/ReDoc).
|
||||||
|
|
||||||
@@ -25,4 +25,4 @@ To test locally, run `make build`, `make run` and navigate to `http://127.0.0.1:
|
|||||||
|
|
||||||
## Deployment
|
## Deployment
|
||||||
|
|
||||||
Deployment is handled automatically by our Jenkins CLI machine. When a pull request is merged it will automatically be deployed to [https://api.mattermost.com](https://api.mattermost.com).
|
Deployment is handled automatically by our Github Actions. When a pull request is merged, it will automatically be deployed to [https://developers.mattermost.com/api-reference](https://developers.mattermost.com/api-reference).
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "mattermost-api-reference",
|
"name": "mattermost-api-reference",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"description": "This repository holds the API reference available at [https://api.mattermost.com](https://api.mattermost.com).",
|
"description": "This repository holds the API reference documentation for Mattermost available at https://developers.mattermost.com/api-reference",
|
||||||
"main": "index.js",
|
"main": "index.js",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@redocly/cli": "^1.13.0",
|
"@redocly/cli": "^1.13.0",
|
||||||
@@ -28,6 +28,5 @@
|
|||||||
"license": "ISC",
|
"license": "ISC",
|
||||||
"bugs": {
|
"bugs": {
|
||||||
"url": "https://github.com/mattermost/mattermost/issues"
|
"url": "https://github.com/mattermost/mattermost/issues"
|
||||||
},
|
}
|
||||||
"homepage": "https://api.mattermost.com/"
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -4,27 +4,25 @@
|
|||||||
<head>
|
<head>
|
||||||
<meta charset="utf8" />
|
<meta charset="utf8" />
|
||||||
<title>Mattermost API Reference</title>
|
<title>Mattermost API Reference</title>
|
||||||
<!-- needed for adaptive design -->
|
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
<link rel="shortcut icon" href="./static/favicon.ico">
|
<link rel="shortcut icon" href="./static/favicon.ico">
|
||||||
|
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
|
||||||
|
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
|
||||||
<style>
|
<style>
|
||||||
body {
|
body {
|
||||||
padding: 0;
|
padding: 0;
|
||||||
margin: 0;
|
margin: 0;
|
||||||
|
height: 100vh;
|
||||||
}
|
}
|
||||||
label[type="tag"] {
|
|
||||||
text-transform: uppercase;
|
|
||||||
}
|
|
||||||
h1{
|
|
||||||
text-transform: capitalize;
|
|
||||||
}
|
|
||||||
</style>
|
</style>
|
||||||
{{{redocHead}}}
|
|
||||||
{{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
|
|
||||||
</head>
|
</head>
|
||||||
|
|
||||||
<body>
|
<body>
|
||||||
{{{redocHTML}}}
|
<elements-api
|
||||||
|
apiDescriptionUrl="./static/mattermost-openapi-v4.yaml"
|
||||||
|
router="hash"
|
||||||
|
layout="sidebar"
|
||||||
|
/>
|
||||||
</body>
|
</body>
|
||||||
|
|
||||||
</html>
|
</html>
|
||||||
|
|||||||
@@ -1,9 +1,8 @@
|
|||||||
components:
|
components:
|
||||||
securitySchemes:
|
securitySchemes:
|
||||||
bearerAuth: # arbitrary name for the security scheme
|
bearerAuth:
|
||||||
type: http
|
type: http
|
||||||
scheme: bearer
|
scheme: bearer
|
||||||
bearerFormat: Token
|
|
||||||
responses:
|
responses:
|
||||||
Forbidden:
|
Forbidden:
|
||||||
description: Do not have appropriate permissions
|
description: Do not have appropriate permissions
|
||||||
|
|||||||
@@ -1,184 +1,173 @@
|
|||||||
openapi: 3.0.0
|
openapi: 3.0.0
|
||||||
info:
|
info:
|
||||||
description: >
|
description: >
|
||||||
There is also a work-in-progress [Postman API
|
The Mattermost Web Services API enables Mattermost clients and third-party applications
|
||||||
reference](https://documenter.getpostman.com/view/4508214/RW8FERUn).
|
to interact with Mattermost servers.
|
||||||
version: 4.0.0
|
|
||||||
title: Mattermost API Reference
|
|
||||||
termsOfService: https://about.mattermost.com/default-terms/
|
|
||||||
contact:
|
|
||||||
email: feedback@mattermost.com
|
|
||||||
x-logo:
|
|
||||||
url: https://mattermost.com/wp-content/uploads/2022/02/logoHorizontal.png
|
|
||||||
backgroundColor: "#FFFFFF"
|
|
||||||
tags:
|
|
||||||
- name: introduction
|
|
||||||
description: >
|
|
||||||
The Mattermost Web Services API is used by Mattermost clients and third
|
|
||||||
party applications to interact with the server. [JavaScript and Golang
|
|
||||||
drivers for](/#tag/drivers) connecting to the APIs are also available.
|
|
||||||
|
|
||||||
|
|
||||||
### Support
|
[Official JavaScript and Golang drivers](#/#official-drivers)
|
||||||
|
are available to simplify API integration.
|
||||||
|
|
||||||
|
|
||||||
Mattermost core committers work with the community to keep the API documentation up-to-date.
|
By using this API, you agree to our [terms of service](https://about.mattermost.com/default-terms/).
|
||||||
|
|
||||||
|
|
||||||
If you have questions on API routes not listed in this reference, please [join the Mattermost community server](https://community.mattermost.com) to ask questions in the Developers channel, [or post questions to our Developer Discussion forum](https://forum.mattermost.org/c/dev).
|
[Find out more about Mattermost](https://about.mattermost.com/)
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
### Core Concepts
|
||||||
|
|
||||||
|
* [Schema & Conventions](#/#schema--conventions)
|
||||||
|
|
||||||
|
* [Authentication](#/#authentication)
|
||||||
|
|
||||||
|
* [Rate Limiting](#/#rate-limiting)
|
||||||
|
|
||||||
|
* [Error Handling](#/#error-handling)
|
||||||
|
|
||||||
|
* [WebSocket](#/#websocket)
|
||||||
|
|
||||||
|
* [Authentication](#/#authentication-1)
|
||||||
|
|
||||||
|
* [Websocket Events](#/#websocket-events)
|
||||||
|
|
||||||
|
* [Websocket API](#/#websocket-api)
|
||||||
|
|
||||||
|
### Drivers
|
||||||
|
|
||||||
|
* [Official Drivers](#/#official-drivers)
|
||||||
|
|
||||||
|
* [Community-built Drivers](#/#community-built-drivers)
|
||||||
|
|
||||||
|
### Community
|
||||||
|
|
||||||
|
* [Support](#/#support)
|
||||||
|
|
||||||
|
* [Contributing](#/#contributing)
|
||||||
|
|
||||||
|
|
||||||
[Bug reports](https://github.com/mattermost/mattermost/issues) in the documentation or the API are also welcome, as are pull requests to fix the issues.
|
## Schema & Conventions
|
||||||
|
|
||||||
|
- All API access is through HTTP(S) requests at `your-mattermost-url/api/v4`.
|
||||||
|
|
||||||
### Contributing
|
- All request and response bodies are `application/json`.
|
||||||
|
|
||||||
|
- When using endpoints that require a user id, the string `me` can be used in place
|
||||||
|
of the user id to indicate the action is to be taken for the logged in user.
|
||||||
|
|
||||||
When you have answers to API questions not addressed in our documentation we ask you to consider making a pull request to improve our reference. Small and large changes are all welcome.
|
- For all endpoints that implement pagination via the `per_page` parameter:
|
||||||
|
|
||||||
|
- Maximum items per page: 200 (requests exceeding this will be silently truncated)
|
||||||
|
|
||||||
We also have [Help Wanted tickets](https://github.com/mattermost/mattermost/issues?q=is%3Aopen+is%3Aissue+label%3AArea%2FAPI) available for community members who would like to help others more easily use the APIs. We acknowledge everyone's contribution in the [release notes of our next version](https://docs.mattermost.com/administration/changelog.html#contributors).
|
- Default value if a paged API requires a `per_page` parameter and it is not provided: 60
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
The source code for this API reference is hosted at https://github.com/mattermost/mattermost/tree/master/api.
|
|
||||||
- name: schema
|
|
||||||
description: >
|
|
||||||
All API access is through HTTP(S) requests at
|
|
||||||
`your-mattermost-url.com/api/v4`. All request and response bodies are
|
|
||||||
`application/json`.
|
|
||||||
|
|
||||||
|
|
||||||
When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user.
|
|
||||||
|
|
||||||
|
|
||||||
For all endpoints that implement pagination via the `per_page` parameter, the maximum number of items returned per request is capped at 200. If `per_page` exceeds 200, the list will be silently truncated to 200 items.
|
|
||||||
- name: drivers
|
|
||||||
description: >
|
|
||||||
The easiest way to interact with the Mattermost Web Service API is through
|
|
||||||
a language specific driver.
|
|
||||||
|
|
||||||
|
|
||||||
#### Official Drivers
|
|
||||||
|
|
||||||
* Mattermost JavaScript/TypeScript Driver
|
|
||||||
* [NPM](https://www.npmjs.com/package/@mattermost/client)
|
|
||||||
* [Source](https://github.com/mattermost/mattermost/tree/master/webapp/platform/client)
|
|
||||||
|
|
||||||
* [Mattermost Golang Driver](https://pkg.go.dev/github.com/mattermost/mattermost/server/public/model#Client4)
|
|
||||||
|
|
||||||
#### Community-built Drivers
|
|
||||||
|
|
||||||
For community-built drivers and API wrappers, see [our app directory](https://mattermost.com/marketplace/).
|
|
||||||
- name: authentication
|
|
||||||
description: >
|
|
||||||
There are multiple ways to authenticate against the Mattermost API.
|
There are multiple ways to authenticate against the Mattermost API.
|
||||||
|
|
||||||
|
|
||||||
All examples assume there is a Mattermost instance running at http://localhost:8065.
|
All examples assume there is a Mattermost instance running at http://localhost:8065.
|
||||||
|
|
||||||
|
### Session Token
|
||||||
|
|
||||||
#### Session Token
|
Make an HTTP POST to `your-mattermost-url/api/v4/users/login` with a JSON
|
||||||
|
body indicating the user's `login_id`, `password` and optionally the MFA
|
||||||
|
`token`. The `login_id` can be an email, username or an AD/LDAP ID
|
||||||
Make an HTTP POST to `your-mattermost-url.com/api/v4/users/login` with a JSON body indicating the user's `login_id`, `password` and optionally the MFA `token`. The `login_id` can be an email, username or an AD/LDAP ID depending on the system's configuration.
|
depending on the system's configuration.
|
||||||
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
|
```bash
|
||||||
curl -i -d '{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v4/users/login
|
curl -i -d '{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v4/users/login
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
NOTE: If you're running cURL on windows, you will have to change the single quotes to double quotes, and escape the inner double quotes with backslash, like below:
|
NOTE: If you're running cURL on windows, you will have to change the single quotes to double quotes, and escape the inner double quotes with backslash, like below:
|
||||||
|
|
||||||
|
|
||||||
```
|
```bash
|
||||||
|
|
||||||
curl -i -d "{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}" http://localhost:8065/api/v4/users/login
|
curl -i -d "{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}" http://localhost:8065/api/v4/users/login
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
If successful, the response will contain a `Token` header and a user object in the body.
|
If successful, the response will contain a `Token` header and a user object in the body.
|
||||||
|
|
||||||
|
```http
|
||||||
```
|
|
||||||
|
|
||||||
HTTP/1.1 200 OK
|
HTTP/1.1 200 OK
|
||||||
|
Content-Type: application/json
|
||||||
Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly
|
Permissions-Policy:
|
||||||
|
Referrer-Policy: no-referrer
|
||||||
Token: hyr5dmb1mbb49c44qmx4whniso
|
Token: ckh3t4knu3fzujt76o57f5jo4w
|
||||||
|
Vary: Origin
|
||||||
X-Ratelimit-Limit: 10
|
Vary: Accept-Encoding
|
||||||
|
X-Content-Type-Options: nosniff
|
||||||
X-Ratelimit-Remaining: 9
|
X-Request-Id: bk3uzm335jr9tnoh4mcsybmmjr
|
||||||
|
X-Version-Id: 10.6.0.13685270376.215f100adf6ccda09afcaaa84ac4bfbd.true
|
||||||
X-Ratelimit-Reset: 1
|
Date: Fri, 28 Mar 2025 09:33:22 GMT
|
||||||
|
Content-Length: 796
|
||||||
X-Request-Id: smda55ckcfy89b6tia58shk5fh
|
|
||||||
|
|
||||||
X-Version-Id: developer
|
|
||||||
|
|
||||||
Date: Fri, 11 Sep 2015 13:21:14 GMT
|
|
||||||
|
|
||||||
Content-Length: 657
|
|
||||||
|
|
||||||
Content-Type: application/json; charset=utf-8
|
|
||||||
|
|
||||||
|
|
||||||
{{user object as json}}
|
{{user object as json}}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
Include the `Token` as part of the `Authorization` header on your future API requests with the `Bearer` method.
|
Include the `Token` as part of the `Authorization` header on your future API requests with the `Bearer` method.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -i -H 'Authorization: Bearer ckh3t4knu3fzujt76o57f5jo4w' http://localhost:8065/api/v4/users/me
|
||||||
```
|
```
|
||||||
|
Alternatively, include the `Token` as your `MMAUTHTOKEN` cookie value on you future API requests:
|
||||||
|
|
||||||
curl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v4/users/me
|
```bash
|
||||||
|
curl -i -H 'Cookie: MMAUTHTOKEN=ckh3t4knu3fzujt76o57f5jo4w' http://localhost:8065/api/v4/users/me
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
You should now be able to access the API as the user you logged in as.
|
You should now be able to access the API as the user you logged in as.
|
||||||
|
|
||||||
|
|
||||||
#### Personal Access Tokens
|
### Personal Access Tokens
|
||||||
|
|
||||||
|
|
||||||
Using [personal access tokens](https://docs.mattermost.com/developer/personal-access-tokens.html) is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin.
|
|
||||||
|
|
||||||
|
Using [personal access tokens](https://developers.mattermost.com/integrate/reference/personal-access-token/) is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin.
|
||||||
|
|
||||||
Just like session tokens, include the personal access token as part of the `Authorization` header in your requests using the `Bearer` method. Assuming our personal access token is `9xuqwrwgstrb3mzrxb83nb357a`, we could use it as shown below.
|
Just like session tokens, include the personal access token as part of the `Authorization` header in your requests using the `Bearer` method. Assuming our personal access token is `9xuqwrwgstrb3mzrxb83nb357a`, we could use it as shown below.
|
||||||
|
|
||||||
|
```bash
|
||||||
```
|
|
||||||
|
|
||||||
curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me
|
curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rate Limiting
|
||||||
|
Whenever you make an HTTP request to the Mattermost API you might notice
|
||||||
|
the following headers included in the response:
|
||||||
|
|
||||||
|
```http
|
||||||
|
X-Ratelimit-Limit: 10
|
||||||
|
X-Ratelimit-Remaining: 9
|
||||||
|
X-Ratelimit-Reset: 1441983590
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
#### OAuth 2.0
|
These headers are telling you your current rate limit status.
|
||||||
|
|
||||||
|
|
||||||
Mattermost has the ability to act as an [OAuth 2.0](https://tools.ietf.org/html/rfc6749) service provider.
|
| Header | Description |
|
||||||
|
|:-----------------------|:-------------------------------------------------------------------|
|
||||||
|
| X-Ratelimit-Limit | The maximum number of requests you can make per second. |
|
||||||
|
| X-Ratelimit-Remaining | The number of requests remaining in the current window. |
|
||||||
|
| X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. |
|
||||||
|
|
||||||
|
If you exceed your rate limit for a window you will receive the following error in the body of the response:
|
||||||
|
|
||||||
The official documentation for [using your Mattermost server as an OAuth 2.0 service provider can be found here.](https://docs.mattermost.com/developer/oauth-2-0-applications.html)
|
```http
|
||||||
|
HTTP/1.1 429 Too Many Requests
|
||||||
|
Date: Tue, 10 Sep 2015 11:20:28 GMT
|
||||||
|
X-RateLimit-Limit: 10
|
||||||
|
X-RateLimit-Remaining: 0
|
||||||
|
X-RateLimit-Reset: 1
|
||||||
|
|
||||||
|
limit exceeded
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
For an example on how to register an OAuth 2.0 app with your Mattermost instance, please see the [Mattermost-Zapier integration documentation](https://docs.mattermost.com/integrations/zapier.html#register-zapier-as-an-oauth-2-0-application).
|
|
||||||
- name: errors
|
|
||||||
description: >
|
|
||||||
All errors will return an appropriate HTTP response code along with the
|
All errors will return an appropriate HTTP response code along with the
|
||||||
following JSON body:
|
following JSON body:
|
||||||
|
|
||||||
```
|
```json
|
||||||
|
|
||||||
{
|
{
|
||||||
"id": "the.error.id",
|
"id": "the.error.id",
|
||||||
"message": "Something went wrong", // the reason for the error
|
"message": "Something went wrong", // the reason for the error
|
||||||
@@ -188,75 +177,21 @@ tags:
|
|||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
- name: rate limiting
|
|
||||||
description: >
|
|
||||||
Whenever you make an HTTP request to the Mattermost API you might notice
|
|
||||||
the following headers included in the response:
|
|
||||||
|
|
||||||
```
|
## WebSocket
|
||||||
|
In addition to the HTTP RESTful web service, Mattermost also offers a WebSocket event delivery system and some API functionality.
|
||||||
|
|
||||||
X-Ratelimit-Limit: 10
|
To connect to the WebSocket follow the standard opening handshake as [defined by the RFC specification](https://tools.ietf.org/html/rfc6455#section-1.3) to the `/api/v4/websocket` endpoint of Mattermost.
|
||||||
|
|
||||||
X-Ratelimit-Remaining: 9
|
|
||||||
|
|
||||||
X-Ratelimit-Reset: 1441983590
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
These headers are telling you your current rate limit status.
|
### Authentication
|
||||||
|
|
||||||
|
|
||||||
| Header | Description |
|
|
||||||
|
|
||||||
| ------ | ----------- |
|
|
||||||
|
|
||||||
| X-Ratelimit-Limit | The maximum number of requests you can make per second. |
|
|
||||||
|
|
||||||
| X-Ratelimit-Remaining | The number of requests remaining in the current window. |
|
|
||||||
|
|
||||||
| X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. |
|
|
||||||
|
|
||||||
|
|
||||||
If you exceed your rate limit for a window you will receive the following error in the body of the response:
|
|
||||||
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
HTTP/1.1 429 Too Many Requests
|
|
||||||
|
|
||||||
Date: Tue, 10 Sep 2015 11:20:28 GMT
|
|
||||||
|
|
||||||
X-RateLimit-Limit: 10
|
|
||||||
|
|
||||||
X-RateLimit-Remaining: 0
|
|
||||||
|
|
||||||
X-RateLimit-Reset: 1
|
|
||||||
|
|
||||||
|
|
||||||
limit exceeded
|
|
||||||
|
|
||||||
```
|
|
||||||
- name: WebSocket
|
|
||||||
description: >
|
|
||||||
In addition to the HTTP RESTful web service, Mattermost also offers a
|
|
||||||
WebSocket event delivery system and some API functionality.
|
|
||||||
|
|
||||||
|
|
||||||
To connect to the WebSocket follow the standard opening handshake as [defined by the RFC specification](https://tools.ietf.org/html/rfc6455#section-1.3) to the `/api/v4/websocket` endpoint of Mattermost.
|
|
||||||
|
|
||||||
|
|
||||||
#### Authentication
|
|
||||||
|
|
||||||
|
|
||||||
The Mattermost WebSocket can be authenticated using [the standard API authentication methods](/#tag/authentication) (by a cookie or with an explicit Authorization header) or through an authentication challenge. If you're authenticating from a browser and have logged in with the Mattermost API, your authentication cookie should already be set. This is how the Mattermost webapp authenticates with the WebSocket.
|
|
||||||
|
|
||||||
|
The Mattermost WebSocket can be authenticated using [the standard API authentication methods](/#/#authentication) (by a cookie or with an explicit Authorization header) or through an authentication challenge. If you're authenticating from a browser and have logged in with the Mattermost API, your authentication cookie should already be set. This is how the Mattermost webapp authenticates with the WebSocket.
|
||||||
|
|
||||||
To authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection:
|
To authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection:
|
||||||
|
|
||||||
|
|
||||||
```
|
```json
|
||||||
|
|
||||||
{
|
{
|
||||||
"seq": 1,
|
"seq": 1,
|
||||||
"action": "authentication_challenge",
|
"action": "authentication_challenge",
|
||||||
@@ -264,37 +199,27 @@ tags:
|
|||||||
"token": "mattermosttokengoeshere"
|
"token": "mattermosttokengoeshere"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
If successful, you will receive a standard OK response over the WebSocket connection:
|
If successful, you will receive a standard OK response over the WebSocket connection:
|
||||||
|
|
||||||
|
|
||||||
```
|
```json
|
||||||
|
|
||||||
{
|
{
|
||||||
"status": "OK",
|
"status": "OK",
|
||||||
"seq_reply": 1
|
"seq_reply": 1
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection.
|
Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection.
|
||||||
|
|
||||||
|
### Websocket Events
|
||||||
#### Events
|
|
||||||
|
|
||||||
|
|
||||||
WebSocket events are primarily used to alert the client to changes in Mattermost, such as delivering new posts or alerting the client that another user is typing in a channel.
|
WebSocket events are primarily used to alert the client to changes in Mattermost, such as delivering new posts or alerting the client that another user is typing in a channel.
|
||||||
|
|
||||||
|
|
||||||
Events on the WebSocket will have the form:
|
Events on the WebSocket will have the form:
|
||||||
|
|
||||||
|
```json
|
||||||
```
|
|
||||||
|
|
||||||
{
|
{
|
||||||
"event": "hello",
|
"event": "hello",
|
||||||
"data": {
|
"data": {
|
||||||
@@ -308,112 +233,62 @@ tags:
|
|||||||
},
|
},
|
||||||
"seq": 0
|
"seq": 0
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
The `event` field indicates the event type, `data` contains any data relevant to the event and `broadcast` contains information about who the event was sent to. For example, the above example has `user_id` set to "ay5sq51sebfh58ktrce5ijtcwy" meaning that only the user with that ID received this event broadcast. The `omit_users` field can contain an array of user IDs that were specifically omitted from receiving the event.
|
The `event` field indicates the event type, `data` contains any data relevant to the event and `broadcast` contains information about who the event was sent to. For example, the above example has `user_id` set to "ay5sq51sebfh58ktrce5ijtcwy" meaning that only the user with that ID received this event broadcast. The `omit_users` field can contain an array of user IDs that were specifically omitted from receiving the event.
|
||||||
|
|
||||||
|
|
||||||
The list of Mattermost WebSocket events are:
|
The list of Mattermost WebSocket events are:
|
||||||
|
|
||||||
- added_to_team
|
- added_to_team
|
||||||
|
|
||||||
- authentication_challenge
|
- authentication_challenge
|
||||||
|
|
||||||
- channel_converted
|
- channel_converted
|
||||||
|
|
||||||
- channel_created
|
- channel_created
|
||||||
|
|
||||||
- channel_deleted
|
- channel_deleted
|
||||||
|
|
||||||
- channel_member_updated
|
- channel_member_updated
|
||||||
|
|
||||||
- channel_updated
|
- channel_updated
|
||||||
|
|
||||||
- channel_viewed
|
- channel_viewed
|
||||||
|
|
||||||
- config_changed
|
- config_changed
|
||||||
|
|
||||||
- delete_team
|
- delete_team
|
||||||
|
|
||||||
- direct_added
|
- direct_added
|
||||||
|
|
||||||
- emoji_added
|
- emoji_added
|
||||||
|
|
||||||
- ephemeral_message
|
- ephemeral_message
|
||||||
|
|
||||||
- group_added
|
- group_added
|
||||||
|
|
||||||
- hello
|
- hello
|
||||||
|
|
||||||
- leave_team
|
- leave_team
|
||||||
|
|
||||||
- license_changed
|
- license_changed
|
||||||
|
|
||||||
- memberrole_updated
|
- memberrole_updated
|
||||||
|
|
||||||
- new_user
|
- new_user
|
||||||
|
|
||||||
- plugin_disabled
|
- plugin_disabled
|
||||||
|
|
||||||
- plugin_enabled
|
- plugin_enabled
|
||||||
|
|
||||||
- plugin_statuses_changed
|
- plugin_statuses_changed
|
||||||
|
|
||||||
- post_deleted
|
- post_deleted
|
||||||
|
|
||||||
- post_edited
|
- post_edited
|
||||||
|
|
||||||
- post_unread
|
- post_unread
|
||||||
|
|
||||||
- posted
|
- posted
|
||||||
|
|
||||||
- preference_changed
|
- preference_changed
|
||||||
|
|
||||||
- preferences_changed
|
- preferences_changed
|
||||||
|
|
||||||
- preferences_deleted
|
- preferences_deleted
|
||||||
|
|
||||||
- reaction_added
|
- reaction_added
|
||||||
|
|
||||||
- reaction_removed
|
- reaction_removed
|
||||||
|
|
||||||
- response
|
- response
|
||||||
|
|
||||||
- role_updated
|
- role_updated
|
||||||
|
|
||||||
- status_change
|
- status_change
|
||||||
|
|
||||||
- typing
|
- typing
|
||||||
|
|
||||||
- update_team
|
- update_team
|
||||||
|
|
||||||
- user_added
|
- user_added
|
||||||
|
|
||||||
- user_removed
|
- user_removed
|
||||||
|
|
||||||
- user_role_updated
|
- user_role_updated
|
||||||
|
|
||||||
- user_updated
|
- user_updated
|
||||||
|
|
||||||
- dialog_opened
|
- dialog_opened
|
||||||
|
|
||||||
- thread_updated
|
- thread_updated
|
||||||
|
|
||||||
- thread_follow_changed
|
- thread_follow_changed
|
||||||
|
|
||||||
- thread_read_changed
|
- thread_read_changed
|
||||||
|
|
||||||
|
### Websocket API
|
||||||
#### WebSocket API
|
|
||||||
|
|
||||||
|
|
||||||
Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection:
|
Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection:
|
||||||
|
|
||||||
|
```json
|
||||||
```
|
|
||||||
|
|
||||||
{
|
{
|
||||||
"action": "user_typing",
|
"action": "user_typing",
|
||||||
"seq": 2,
|
"seq": 2,
|
||||||
@@ -422,37 +297,28 @@ tags:
|
|||||||
"parent_id": ""
|
"parent_id": ""
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
This is an example of making a `user_typing` request, with the purpose of alerting the server that the connected client has begun typing in a channel or thread. The `action` field indicates what is being requested, and performs a similar duty as the route in a HTTP API. The `data` field is used to add any additional data along with the request. The server supports binary websocket messages as well in case the client has such a requirement.
|
This is an example of making a `user_typing` request, with the purpose of alerting the server that the connected client has begun typing in a channel or thread. The `action` field indicates what is being requested, and performs a similar duty as the route in a HTTP API. The `data` field is used to add any additional data along with the request. The server supports binary websocket messages as well in case the client has such a requirement.
|
||||||
|
|
||||||
|
|
||||||
The `seq` or sequence number is set by the client and should be incremented with every use. It is used to distinguish responses to requests that come down the WebSocket. For example, a standard response to the above request would be:
|
The `seq` or sequence number is set by the client and should be incremented with every use. It is used to distinguish responses to requests that come down the WebSocket. For example, a standard response to the above request would be:
|
||||||
|
|
||||||
|
|
||||||
```
|
```json
|
||||||
|
|
||||||
{
|
{
|
||||||
"status": "OK",
|
"status": "OK",
|
||||||
"seq_reply": 2
|
"seq_reply": 2
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
Notice `seq_reply` is 2, matching the `seq` of the original request. Using this a client can distinguish which request the response is meant for.
|
Notice `seq_reply` is 2, matching the `seq` of the original request. Using this a client can distinguish which request the response is meant for.
|
||||||
|
|
||||||
|
|
||||||
If there was any information to respond with, it would be encapsulated in a `data` field.
|
If there was any information to respond with, it would be encapsulated in a `data` field.
|
||||||
|
|
||||||
|
|
||||||
In the case of an error, the response would be:
|
In the case of an error, the response would be:
|
||||||
|
|
||||||
|
|
||||||
```
|
```json
|
||||||
|
|
||||||
{
|
{
|
||||||
"status": "FAIL",
|
"status": "FAIL",
|
||||||
"seq_reply": 2,
|
"seq_reply": 2,
|
||||||
@@ -461,32 +327,65 @@ tags:
|
|||||||
"message": "Some error message here"
|
"message": "Some error message here"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
The list of WebSocket API actions is:
|
The list of WebSocket API actions is:
|
||||||
|
|
||||||
- user_typing
|
- user_typing
|
||||||
|
|
||||||
- get_statuses
|
- get_statuses
|
||||||
|
|
||||||
- get_statuses_by_ids
|
- get_statuses_by_ids
|
||||||
|
|
||||||
|
|
||||||
To see how these actions work, please refer to either the [Golang WebSocket driver](https://github.com/mattermost/mattermost/blob/master/server/public/model/websocket_client.go) or our [JavaScript WebSocket driver](https://github.com/mattermost/mattermost/blob/master/webapp/platform/client/src/websocket.ts).
|
To see how these actions work, please refer to either the [Golang WebSocket driver](https://github.com/mattermost/mattermost/blob/master/server/public/model/websocket_client.go) or our [JavaScript WebSocket driver](https://github.com/mattermost/mattermost/blob/master/webapp/platform/client/src/websocket.ts).
|
||||||
- name: common parameters
|
|
||||||
description: >
|
|
||||||
- `per_page`: For paged APIs, the number of items to return per page.
|
|
||||||
|
|
||||||
The maximum number of items returned per request is capped at 200. If `per_page` exceeds 200, the list will be silently truncated to 200 items.
|
## Drivers
|
||||||
|
The easiest way to interact with the Mattermost Web Service API is through
|
||||||
|
a language specific driver.
|
||||||
|
|
||||||
If a paged API requires a `per_page` parameter and it is not provided, the default value is 60.
|
### Official Drivers
|
||||||
|
|
||||||
|
* Mattermost JavaScript/TypeScript Driver
|
||||||
|
* [NPM](https://www.npmjs.com/package/@mattermost/client)
|
||||||
|
* [Source](https://github.com/mattermost/mattermost/tree/master/webapp/platform/client)
|
||||||
|
|
||||||
|
* [Mattermost Golang Driver](https://pkg.go.dev/github.com/mattermost/mattermost/server/public/model#Client4)
|
||||||
|
|
||||||
|
### Community-built Drivers
|
||||||
|
|
||||||
|
For community-built drivers and API wrappers, see [our app directory](https://mattermost.com/marketplace-category/mattermost-developers-tools/).
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Mattermost core committers work with the community to keep the API documentation up-to-date.
|
||||||
|
|
||||||
|
If you have questions on API routes not listed in this reference, you can:
|
||||||
|
|
||||||
|
- [Join the Mattermost community server](https://community.mattermost.com) to ask questions in the Developers channel
|
||||||
|
|
||||||
|
- Contact us at feedback@mattermost.com
|
||||||
|
|
||||||
|
|
||||||
|
[Bug reports](https://github.com/mattermost/mattermost/issues) in the documentation or the API are also welcome, as are pull requests to fix the issues.
|
||||||
|
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
When you have answers to API questions not addressed in our documentation we ask you to consider making a pull request to improve our reference. Small and large changes are all welcome.
|
||||||
|
|
||||||
|
|
||||||
|
We also have [Help Wanted tickets](https://github.com/mattermost/mattermost/issues?q=is%3Aopen+is%3Aissue+label%3AArea%2FAPI) available for community members who would like to help others more easily use the APIs. We acknowledge everyone's contribution in the [release notes of our next version](https://docs.mattermost.com/administration/changelog.html#contributors).
|
||||||
|
|
||||||
|
|
||||||
|
The source code for this API reference is hosted at https://github.com/mattermost/mattermost/tree/master/api.
|
||||||
|
|
||||||
|
version: 4.0.0
|
||||||
|
title: Mattermost API
|
||||||
|
tags:
|
||||||
- name: users
|
- name: users
|
||||||
description: >
|
description: >
|
||||||
Endpoints for creating, getting and interacting with users.
|
Endpoints for creating, getting and interacting with users.
|
||||||
|
|
||||||
|
|
||||||
When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user.
|
When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user.
|
||||||
- name: bots
|
- name: bots
|
||||||
description: Endpoints for creating, getting and updating bot users.
|
description: Endpoints for creating, getting and updating bot users.
|
||||||
@@ -563,65 +462,9 @@ tags:
|
|||||||
description: Endpoints related to metrics, including the Client Performance Monitoring feature.
|
description: Endpoints related to metrics, including the Client Performance Monitoring feature.
|
||||||
- name: audit_logs
|
- name: audit_logs
|
||||||
description: Endpoints for managing audit log certificates and configuration.
|
description: Endpoints for managing audit log certificates and configuration.
|
||||||
x-tagGroups:
|
|
||||||
- name: Overview
|
|
||||||
tags:
|
|
||||||
- introduction
|
|
||||||
- schema
|
|
||||||
- name: Standard Features
|
|
||||||
tags:
|
|
||||||
- drivers
|
|
||||||
- authentication
|
|
||||||
- errors
|
|
||||||
- rate limiting
|
|
||||||
- WebSocket
|
|
||||||
- common parameters
|
|
||||||
- name: Endpoints
|
|
||||||
tags:
|
|
||||||
- users
|
|
||||||
- bots
|
|
||||||
- teams
|
|
||||||
- channels
|
|
||||||
- posts
|
|
||||||
- threads
|
|
||||||
- files
|
|
||||||
- uploads
|
|
||||||
- bookmarks
|
|
||||||
- preferences
|
|
||||||
- status
|
|
||||||
- emoji
|
|
||||||
- reactions
|
|
||||||
- webhooks
|
|
||||||
- commands
|
|
||||||
- system
|
|
||||||
- brand
|
|
||||||
- OAuth
|
|
||||||
- SAML
|
|
||||||
- LDAP
|
|
||||||
- groups
|
|
||||||
- compliance
|
|
||||||
- cluster
|
|
||||||
- cloud
|
|
||||||
- elasticsearch
|
|
||||||
- bleve
|
|
||||||
- data retention
|
|
||||||
- jobs
|
|
||||||
- plugins
|
|
||||||
- roles
|
|
||||||
- schemes
|
|
||||||
- integration_actions
|
|
||||||
- remote clusters
|
|
||||||
- shared channels
|
|
||||||
- terms of service
|
|
||||||
- imports
|
|
||||||
- permissions
|
|
||||||
- exports
|
|
||||||
- usage
|
|
||||||
- reports
|
|
||||||
- custom profile attributes
|
|
||||||
- metrics
|
|
||||||
- audit_logs
|
|
||||||
servers:
|
servers:
|
||||||
- url: http://your-mattermost-url.com
|
- url: "{your-mattermost-url}"
|
||||||
- url: https://your-mattermost-url.com
|
variables:
|
||||||
|
your-mattermost-url:
|
||||||
|
default: http://localhost:8065
|
||||||
paths:
|
paths:
|
||||||
|
|||||||
Ссылка в новой задаче
Block a user