mirror of
https://github.com/mattermost/focalboard.git
synced 2024-12-24 13:43:12 +02:00
76 lines
2.6 KiB
Markdown
Generated
76 lines
2.6 KiB
Markdown
Generated
# Swagger / OpenAPI 2.0 auto-generated files
|
|
|
|
⚠️ **Warning:** The API is currently considered Beta and major changes are planned. Please [see this note](https://github.com/mattermost/focalboard/discussions/2139) for more details.
|
|
|
|
This folder is generated by the `make swagger` command from comments in the server code.
|
|
|
|
Prerequisites:
|
|
1. [go-swagger](https://goswagger.io/install.html)
|
|
2. [openapi-generator](https://github.com/OpenAPITools/openapi-generator)
|
|
|
|
These can be installed via Homebrew:
|
|
```
|
|
brew tap go-swagger/go-swagger
|
|
brew install go-swagger
|
|
brew install openapi-generator
|
|
```
|
|
|
|
# Server API documentation
|
|
|
|
See the generated [server API documentation here](https://htmlpreview.github.io/?https://github.com/mattermost/focalboard/blob/main/server/swagger/docs/html/index.html).
|
|
|
|
# How to authenticate
|
|
|
|
To auth against Personal Server, first call login with your credentials to get a token, e.g.
|
|
```
|
|
curl -X POST \
|
|
-H "Accept: application/json" \
|
|
-H "X-Requested-With: XMLHttpRequest" \
|
|
-H "Content-Type: application/json" \
|
|
"http://localhost:8000/api/v2/login" \
|
|
-d '{
|
|
"type" : "normal",
|
|
"username" : "testuser",
|
|
"password" : "testpass"
|
|
}'
|
|
```
|
|
|
|
This should return a token in the form:
|
|
```
|
|
{"token":"abcdefghijklmnopqrstuvwxyz1"}
|
|
```
|
|
|
|
Pass this as the bearer auth to subsequent calls, e.g.
|
|
```
|
|
curl -X GET \
|
|
-H "Accept: application/json" \
|
|
-H "Authorization: Bearer abcdefghijklmnopqrstuvwxyz1" \
|
|
-H "X-Requested-With: XMLHttpRequest" \
|
|
-H "Content-Type: application/json" \
|
|
"http://localhost:8000/api/v2/teams/0/boards"
|
|
```
|
|
|
|
# Differences for Mattermost Boards
|
|
|
|
The auto-generated Swagger API documentation is for Focalboard Personal Server. If you are calling the API on Mattermost Boards, the additional changes are:
|
|
|
|
### API URLs endpoint
|
|
|
|
The API endpoint is at `https://SERVERNAME/plugins/focalboard/api/`, e.g. `https://community.mattermost.com/plugins/focalboard/api/`.
|
|
|
|
### Use the Mattermost auth token
|
|
|
|
Refer to the [Mattermost API documentation here](https://api.mattermost.com/#tag/authentication) on how to obtain the auth token.
|
|
|
|
Pass this token as a bearer token to the Boards APIs, e.g.
|
|
|
|
```
|
|
curl -i -H "X-Requested-With: XMLHttpRequest" -H 'Authorization: Bearer abcdefghijklmnopqrstuvwxyz' https://community.mattermost.com/plugins/focalboard/api/v2/workspaces
|
|
```
|
|
|
|
Note that the `X-Requested-With: XMLHttpRequest` header is required to pass the CSRF check.
|
|
|
|
# We want to hear from you!
|
|
|
|
If you are planning on using the Boards API, we would love to hear about what you'd like to do, and how we can improve the APIs in the future. [See here](https://github.com/mattermost/focalboard/discussions/2139) for more details on how to connect.
|