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 c