Concepts clés

Structure de l’API

L’API Frame.io prend en charge des concepts courants comme la limitation de débit, la pagination pour les collections de ressources, le contrôle de version et les erreurs. Cette section décrit les spécificités de chacun.

Organisation et style

L’API est organisée autour de principes REST courants. Toutes les requêtes doivent être effectuées via SSL. Tous les corps de requête et de réponse, y compris les erreurs, sont encodés en JSON.

Sauf indication contraire, les méthodes d’API respectent ce qui suit :

• Les propriétés sans valeur utiliseront null au lieu d’être non définies * Le « Snake Case » est utilisé pour les noms d’attribut (par ex. first_name) * Les dates et heures sont rendues au format ISO-8601 (par ex. 2016-02-03T16:38:46.985Z)

Conventions de chemin d’accès

Comptes > Équipes > Projets > Ressources > Commentaires

En général, les chemins d’accès de ressources dans l’API Frame.io suivront le modèle de hiérarchie ci-dessus, jusqu’à un niveau parent. Quand cela est intuitif, l’API prend en charge les chemins d’accès de ressources autonomes pour les objets qui sont strictement détenus, logiquement parlant.

Par exemple, l’API Frame.io prend en charge les deux chemins d’accès suivants :

• GET /accounts/:id/teams — renvoie toutes les équipes d’un compte. * GET /teams — renvoie toutes les équipes de l’utilisateur appelant. * GET /teams/:id — renvoie les détails d’une équipe spécifique.

Autre exemple : les commentaires n’ont pas beaucoup de sens en dehors de leur contexte de ressource, donc les méthodes de collection et de création de commentaires se trouvent dans la portée de la ressource. Cependant, lors de la mise à jour ou de la suppression d’un commentaire, le contexte de la ressource n’est pas aussi significatif et est omis du chemin d’accès de la ressource :

• GET /assets/:id/comments * POST /assets/:id/comments * PUT /comments/:id * DELETE /comments/:id

Portées

Que vous récupériez un jeton via OAuth2.0 ou directement via le Portail développeur, tous les jetons d’API doivent être associés à une liste explicite de « portées », qui font référence à une combinaison d’une ressource (par ex. Ressource) et d’une action (par ex. créer), et sont exprimées avec la notation par points. Par exemple, un jeton avec la portée asset.create pourrait créer de nouvelles ressources.

Si vous utilisez une implémentation avec un jeton de développeur, alors les portées sont définies et attribuées au jeton d’accès lui-même. Si vous utilisez une application OAuth, les portées sont définies pour l’application, et lorsque les utilisateurs interagissent avec l’application pour la première fois, ils acceptent d’octroyer à l’application l’autorisation d’agir avec les portées demandées.

Les portées disponibles pour les jetons de développeur et les applications incluent les éléments suivants (veuillez noter que certaines portées ne sont pas disponibles pour tout le monde, et elles sont signalées en cas de problème).

Pagination

Les méthodes API qui renvoient une collection de résultats sont toujours paginées. Toutes les méthodes qui attendent des résultats paginés répondront aux paramètres de requête suivants et renverront les attributs d’en-tête suivants :

• next — l’URL correspondante est le lien vers la page suivante.
• prev — l’URL correspondante est le lien vers la page précédente.
• last — l’URL correspondante est le lien vers la dernière page.

Remarque : lorsque ni les liens next ni prev ne sont présents, cela indique que la première page renvoyée est la seule page.