focalboard/server/swagger/README.md

# 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.