APIv4 Development Process

This page documents the process for implementing endpoints for version 4 of the Mattermost REST API. If you have questions please ask in the APIv4 channel. The project leads are Joram Wilander (@joram) on development and Jason Blais (@jason) on product management.

Looking for the API reference? That can be found here: https://api.mattermost.com/v4.

Adding an Endpoint

To add an endpoint to API version 4, each item on the following checklist must be completed:

A full example can be found through these two pull requests:

Documenting the Endpoint

At Mattermost we use the OpenAPI specification for API documentation. That documentation lives in the mattermost-api-reference repository. To document an endpoint, follow these steps:

  1. Fork mattermost-api-reference and create a branch for your changes.
  2. Find the .yaml file in the /source/v4 directory that fits your endpoint.
    • For example, if you were adding the GET /users/{user_id} endpoint you would be looking for users.yaml
    • If the file doesn’t exist yet, you might need to create it and update the Makefile to include it
  3. Copy an existing endpoint from the same or a different file.
  4. Update the documention you copied with the correct information for your endpoint, including:
    • Tag - The resource type
    • Summary - A few word summary
    • Description - A brief 1-2 sentence description
    • Permissions - The permission required
    • Parameters - The URL and body parameters
    • Responses - The success and error responses
  5. Confirm you don’t have any syntax errors by running make build-v4 and copying /html/static/mattermost-openapi-v4.yaml into the Swagger editor.
  6. Commit your changes and submit a pull request to mattermost-api-reference.

If you’re looking for examples, see users.yaml.

Implementing the API Handler

To implement the API handler you’ll first need to setup your developer environment, then follow these steps:

  1. Add the declaration for your endpoint.

  2. Implement the handler for your endpoint.

    • The general pattern for handlers is

  3. Run the server using make run-server to check for syntax errors.

  4. (Optional) Use curl or Postman to test the basics of your endpoint. The endpoint will also be tested through a unit test, so this step is optional.

Updating the Go Driver

The Go driver for APIv4 is in /model/client4.go.

To add a function to support your new endpoint:

  1. Copy an existing driver function, such as CreateUser.
  2. Paste the function into the section for your endpoint.
    • For example, POST /teams would go in the Teams section
  3. Modify the function to correctly hit your endpoint.
    • Make sure to update the request method to match your endpoint’s HTTP method

That’s it, you’ll be able to test your function in the next section.

Writing a Unit Test

The most important part of this process is to make sure your endpoint works correctly. Follow these steps to write a test:

  1. Open the test Go file related to your endpoint.
  2. Write your test based on the other tests in your file
  3. Make sure your test covers the following:
    • All combinations of correct inputs to your endpoint
    • Etags for your endpoint, if applicable
    • Incorrect URL or body parameters return a 400 Bad Request status code
    • Requests without a token return a 401 Unauthorized status code (for endpoints requiring a session)
    • Requests with insufficent permissions return a 403 Forbidden status code (for endpoints requiring a permission)
    • Requests to non-existent resources or URLs return a 404 Not Found status code

Returning the correct error code might require investigation in the app or store packages to find the source of errors. Status codes on errors should be set at the creation of the error.

When completing this step, please make sure to use the new model.NewAppError() function (see example).

Submitting your Pull Request

Please submit a pull request against the mattermost/platform repository by following these instructions.