API REST

Intégrez vos propres systèmes à mTime via son API REST.

Aperçu

Tout ce qu’une intégration client peut appeler est décrit dans la référence de l'API — la liste complète et toujours à jour des endpoints, des formats de requête et de réponse, ainsi qu’un journal des changements incompatibles. Le même document est disponible sous forme lisible par machine sur /api/openapi.yaml (OpenAPI 3.1).

L’API est servie sous /api sur le même hôte que l’application, par exemple https://mtime.app/api.

Authentification

L’accès à l’API passe toujours par un utilisateur de service — un utilisateur non personnel représentant une intégration — et ses clés API. La création des deux est décrite dans Utilisateurs et autorisations.

Envoyez la clé comme jeton bearer sur chaque requête :

Authorization: Bearer mtime_ak_...

Versions de l’API

L’API est versionnée par date. Votre intégration porte une date de compatibilité — le jour où elle a été écrite par rapport à l’API — et chaque endpoint répond avec la forme qu’il avait ce jour-là, même si l’endpoint a changé depuis. Les nouveaux endpoints et les autres ajouts compatibles vous parviennent quelle que soit votre date.

• À la création d’un utilisateur de service, sa date de compatibilité est fixée à ce jour, si bien qu’un changement incompatible futur ne surprend jamais l’intégration.
• La date réellement utilisée est renvoyée sur chaque réponse dans l’en-tête X-Mtime-Api-Version. Vous pouvez aussi envoyer cet en-tête sur une requête pour remplacer la date enregistrée le temps d’un appel.
• Un administrateur peut avancer la date enregistrée — pour tout l’utilisateur de service ou pour une seule clé API — sous Admin › Utilisateurs. Faites-le délibérément, après avoir mis à jour l’intégration à partir du journal des changements.

Changements incompatibles et dépréciation

Seuls les changements incompatibles avec l’existant créent une nouvelle version, et chacun est documenté — ce qui a changé et pourquoi — dans la section Breaking changes de la référence de l'API.

Quand une forme est remplacée, l’ancienne continue de servir les appelants épinglés avant le changement pendant au moins 18 mois. Une fois son retrait planifié, les réponses qu’elle sert portent les en-têtes Deprecation et Sunset, et mTime avertit les administrateurs sous Admin › Utilisateurs des utilisateurs de service et clés API encore épinglés à la version en cours de retrait.