M-TOOLS API documentation (1.0.0)

Download OpenAPI specification:Download

License: commercial

Introduction

Welcome to the M-TOOLS 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.

Localization

Accept-Language header

All clients must set the standard Accept-Language HTTP header explicitly and manually to the IETF language tag (en-US) or ISO639-1 (en) locale chosen by the client for client-side message localization.

The reason for this is aligning translated messages stored and shown on the client side with those from the backend, most notably on validation error messages. For example if a client supports only en and de but the device is actually set fr, if the client does not explicitly state which language it picked the backend might make a differing choice based on available backend languages or configured default fallback language.

Note that this does not affect "core" translations, which should not be fetched from the backend dynamically but be defined and used in the clients themselves.

Additionally the backend stores the user's current language to use for server-side issued user-facing communication like e-mails and push notifications.

Determining available languages

From the total pool of supported languages, only a subset is enabled for any tenant, and one of these is the default locale.

Clients must use only available locales for the tenant, so if a tenant supports en and de and has a default of de, if fr is also a M-TOOLS supported language a client on a device configured to be fr locale must then fall back to the default locale de, because fr is not in the enabled list.

For mobile apps, the default and supported locales are baked in the apps at compile time currently. For web clients the frontend configuration endpoint is used

Working with CDN images

Many resources contain images URLs that should be displayed to the user. We host these images through the Cloudinary CDN at the highest available resolution and quality, i.e. collecting SVG images where possible and so on.

In order for clients to be able to use those images at the contextually required size and format cloudinary transformations must be utilized:

Take for example this cloudinary URL:

https://res.cloudinary.com/mtools/image/upload/v1587046313/production/m-tools-hailing-demo/dashboard_wallpaper-526ba6aaa06baeaf567d3a53dc41b095.jpg

In order to enforce PNG format and a 400px width, you must inject w_400,f_png into the /image/upload/TRANSFORMS/v part:

https://res.cloudinary.com/mtools/image/upload/w_400,f_png/v1587046313/production/m-tools-hailing-demo/dashboard_wallpaper-526ba6aaa06baeaf567d3a53dc41b095.jpg

Please note that Cloudinary offers client side SDKs, however we recommend not to use them because:

  • We do not use the majority of their features, like uploads, so they add bloat
  • They must be initialized with another token that needs to be managed

Instead, please just use simple string substition to inject your desired parameters the way you need them. Here's a very basic example method in Ruby:

def cloudinary_transform(url, width:, format:)
  url.sub "/image/upload/v", "/image/upload/w_\#{width},f_\#{format}/v"
end

Images have cache-busting URLs, so if they change their URL will change. Therefore, it's safe to cache them long-term.

Authentication

BearerAuth

Authenticated endpoints use Bearer token authentication in the shape of an Authorization: Bearer <THETOKEN> HTTP request header.

Two kinds of tokens exist:

  • Access tokens
  • API tokens

The former is used for client applications. It is issued by signup, signin and refresh token endpoints and must be used alongside an identifying, valid X-Client-Version header value.

API tokens are issued via the web dashboard and are intended for programmatic API access like 3rd party service integrations and other automations. When using an API token the X-Client-Version header must be omitted.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Uploads

Endpoints for uploading files for attaching against other resources.

Upload Image

Upload images for later usage as attachments to other resources.

You need to send the file as a multipart/form-data content type and the file itself should be the upload[file] parameter, for example using curl:

curl -F 'upload[file]=@/tmp/myfile.jpg' <AUTH_HEADERS> <BACKEND_URL>

Make sure to hold on to the returned ID, you will need it later!

Authorizations:
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json, application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: multipart/form-data
required
object

Responses