MotionTools API documentation (1.0.0)

Download OpenAPI specification:Download

License: commercial

Introduction

Welcome to the MotionTools API documentation!

Client Identification

Please note that when using API Token authentication this header must not be set!

All clients must set the X-Client-Version header to their applicable Client ID and Version, like MyCustomerApp/1.0.0. The header is used for identifying the applicable tenant to enable multi-tenancy, as well as for enabling the expiration of outdated clients.

  • If the client version is disallowed the backend will send a 410 Gone HTTP response code. Upon this response clients must show a notification to the user to upgrade their app.
  • If the client version is unknown the backend will return a 400 HTTP response with the unknown_tenant error code.
  • Some client versions are permitted only for a specific user role. This is currently only enforced on sign up and sign in routes, which will render the user unable to obtain an access/refresh token. If the client is being used by a user that doesn't have a supported role, a 403 HTTP response code will be returned with the error_code client_role_mismatch. It's up to the client to handle this specific status and error code combination gracefully.

Deprecations

X-Deprecated header is returned only on staging if a deprecated endpoint is called, or if a deprecated param is passed. When a deprecated endpoint is called, this header will have deprecated_action as value. If a deprecated param (or params) is passed, then the name of this param will be the value.

Errors

Errors are broadly indicated via HTTP status and further narrowed down using an error code in the response payload. Human-readable descriptions are implementor-facing and meant to help in understanding issues, not user-facing.

{
  "error_code": "hello_world",
  "description": "Some brief description"
}

Some errors like failed validations may contain additional data in the response in order to clarify to the user what was wrong more easily. These messages are localized based on the sent Accept-Language and should be displayed as applicable:

  • If an error key matches a request parameter the messages can be displayed along that field
  • If an unknown error key is encountered (this can happen for multi-parameter composite validations like "one of email or phone must be set") all those messages should be displayed in a central place on top or at the bottom of the UI

A validation error response looks like this:

{
  "errors": { first_name: ["is blank"] }