upstream/mattermost
1
0
Fork 0
mirror of https://github.com/mattermost/mattermost.git synced 2026-02-03 20:40:00 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

feat: Switch from Redoc to Stoplight Elements for API documentation (#30591)

Browse source
This commit is contained in:
Eva Sarafianou 2025-04-17 12:31:56 +03:00 committed by GitHub
parent e00cccd33f
commit b548a8f336
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 176 additions and 343 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.github/workflows/api.yml vendored
View file

@ -28,8 +28,3 @@ jobs:
- name: Run build
run: make build
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: mattermost-api-reference
path: api/v4/html

7
api/Makefile
View file

@ -66,7 +66,7 @@ build-v4: node_modules playbooks
cd server && go run . $(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
node_modules: package.json $(wildcard package-lock.json)
@ -76,9 +76,8 @@ node_modules: package.json $(wildcard package-lock.json)
touch $@
run:
@echo Starting redoc server
@node_modules/.bin/redocly preview-docs ./v4/html/static/mattermost-openapi-v4.yaml
@echo Starting local server
python3 -m http.server 8080 --directory ./v4/html
clean:
@echo Cleaning

4
api/README.md
View file

@ -1,6 +1,6 @@
# 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).
@ -25,4 +25,4 @@ To test locally, run `make build`, `make run` and navigate to `http://127.0.0.1:
## 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).

5
api/package.json
View file

@ -1,7 +1,7 @@
{
"name": "mattermost-api-reference",
"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",
"dependencies": {
"@redocly/cli": "^1.13.0",
@ -28,6 +28,5 @@
"license": "ISC",
"bugs": {
"url": "https://github.com/mattermost/mattermost/issues"
},
"homepage": "https://api.mattermost.com/"
}
}

18
api/v4/html/ssr_template.hbs
View file

@ -4,27 +4,25 @@
<head>
<meta charset="utf8" />
<title>Mattermost API Reference</title>
<!-- needed for adaptive design -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<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>
body {
padding: 0;
margin: 0;
height: 100vh;
}
label[type="tag"] {
text-transform: uppercase;
}
h1{
text-transform: capitalize;
}
</style>
{{{redocHead}}}
{{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
</head>
<body>
{{{redocHTML}}}
<elements-api
apiDescriptionUrl="./static/mattermost-openapi-v4.yaml"
router="hash"
layout="sidebar"
/>
</body>
</html>

3
api/v4/source/definitions.yaml
View file

@ -1,9 +1,8 @@
components:
securitySchemes:
bearerAuth: # arbitrary name for the security scheme
bearerAuth:
type: http
scheme: bearer
bearerFormat: Token
responses:
Forbidden:
description: Do not have appropriate permissions

477
api/v4/source/introduction.yaml
View file

@ -1,184 +1,173 @@
openapi: 3.0.0
info:
description: >
There is also a work-in-progress [Postman API
reference](https://documenter.getpostman.com/view/4508214/RW8FERUn).
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.
The Mattermost Web Services API enables Mattermost clients and third-party applications
to interact with Mattermost servers.
### 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.
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.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.
```
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
depending on the system's configuration.
```bash
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:
```
```bash
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.
```
```http
HTTP/1.1 200 OK
Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly
Token: hyr5dmb1mbb49c44qmx4whniso
X-Ratelimit-Limit: 10
X-Ratelimit-Remaining: 9
X-Ratelimit-Reset: 1
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
Content-Type: application/json
Permissions-Policy:
Referrer-Policy: no-referrer
Token: ckh3t4knu3fzujt76o57f5jo4w
Vary: Origin
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
X-Request-Id: bk3uzm335jr9tnoh4mcsybmmjr
X-Version-Id: 10.6.0.13685270376.215f100adf6ccda09afcaaa84ac4bfbd.true
Date: Fri, 28 Mar 2025 09:33:22 GMT
Content-Length: 796
{{user object as json}}
```
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.
#### 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.
### Personal Access Tokens
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.
```
```bash
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
following JSON body:
```
```json
{
"id": "the.error.id",
"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
X-Ratelimit-Remaining: 9
X-Ratelimit-Reset: 1441983590
```
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.
These headers are telling you your current rate limit status.
| 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.
### Authentication
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:
```
```json
{
"seq": 1,
"action": "authentication_challenge",
@ -264,37 +199,27 @@ tags:
"token": "mattermosttokengoeshere"
}
}
```
If successful, you will receive a standard OK response over the WebSocket connection:
```
```json
{
"status": "OK",
"seq_reply": 1
}
```
Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection.
#### Events
### Websocket 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.
Events on the WebSocket will have the form:
```
```json
{
"event": "hello",
"data": {
@ -308,112 +233,62 @@ tags:
},
"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 list of Mattermost WebSocket events are:
- added_to_team
- authentication_challenge
- channel_converted
- channel_created
- channel_deleted
- channel_member_updated
- channel_updated
- channel_viewed
- config_changed
- delete_team
- direct_added
- emoji_added
- ephemeral_message
- group_added
- hello
- leave_team
- license_changed
- memberrole_updated
- new_user
- plugin_disabled
- plugin_enabled
- plugin_statuses_changed
- post_deleted
- post_edited
- post_unread
- posted
- preference_changed
- preferences_changed
- preferences_deleted
- reaction_added
- reaction_removed
- response
- role_updated
- status_change
- typing
- update_team
- user_added
- user_removed
- user_role_updated
- user_updated
- dialog_opened
- thread_updated
- thread_follow_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:
```
```json
{
"action": "user_typing",
"seq": 2,
@ -422,37 +297,28 @@ tags:
"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.
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",
"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.
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:
```
```json
{
"status": "FAIL",
"seq_reply": 2,
@ -461,32 +327,65 @@ tags:
"message": "Some error message here"
}
}
```
The list of WebSocket API actions is:
- user_typing
- get_statuses
- 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).
- 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
description: >
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.
- name: bots
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.
- name: audit_logs
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:
- url: http://your-mattermost-url.com
- url: https://your-mattermost-url.com
- url: "{your-mattermost-url}"
variables:
your-mattermost-url:
default: http://localhost:8065
paths: