Guide de prise en main

Adobe Developer Console

La première étape pour utiliser une API Adobe consiste à créer un projet dans l’Adobe Developer Console. Les projets de la Developer Console correspondent à une application que vous développez pour utiliser l’API de développement Frame.io. Cela diffère d’un projet dans Frame.io.

Après avoir créé un projet dans la Developer Console, ajoutez-y l’API Frame.io.

Quelles sont les nouveautés de l’API de développement Frame.io V4 ?

Tout comme l’application Frame.io a été entièrement repensée pour la version 4, l’API V4 a également été entièrement remaniée. Bien que certains concepts clés restent semblables à ceux des versions précédentes, beaucoup ont été remplacés ou repensés afin de prendre en charge des intégrations et des workflows collaboratifs plus performants. La mise en place d’une toute nouvelle API nous a également permis de simplifier considérablement nos opérations et de donner la priorité aux workflows essentiels pour nos clients.

Au sein de l’API V4, certaines ressources, telles que les « espaces de travail » (auparavant appelés « Équipes » dans la version héritée de Frame.io), ont été renommées afin de s’aligner sur la version 4 de Frame.io, tandis que d’autres, comme les « Ressources » de la version héritée, ont été renommées pour désigner des entités de stockage spécifiques (fichiers, dossiers et piles de versions) afin d’éviter toute confusion chez les développeurs. D’autres encore, comme les Champs personnalisés et les Partages, sont entièrement nouvelles. Parmi les autres changements majeurs, nous avons considérablement réduit la quantité de données renvoyées par défaut lors des requêtes de ressources, renommé certaines propriétés dans nos réponses afin d’assurer une plus grande précision et une meilleure cohérence à l’échelle de l’ensemble de l’API, et adopté un nouveau mécanisme de pagination basé sur un curseur. Il est donc important de noter que, à l’exception de l’API Camera to Cloud (C2C), les clients qui s’intègrent à l’API héritée ne sont pas compatibles avec l’API V4.

Par ailleurs, certaines fonctionnalités sont encore en cours de développement et devraient être mises en place et évoluer rapidement en fonction des cas d’utilisation concrets des clients et de leurs retours d’expérience. On peut citer, par exemple, la possibilité de créer des actions personnalisées et des piles de versions. Si une fonctionnalité qui était auparavant disponible dans notre API héritée semble manquer, il est fort probable qu’il existe une alternative ou qu’elle soit bientôt disponible, mais nous aimerions connaître votre avis à ce sujet.

Avant de se plonger dans l’API V4, il est utile de bien comprendre les concepts fondamentaux présentés dans l’application Frame.io version 4. Un bon point de départ est la base de connaissances de Frame.io V4. Des concepts tels que les comptes, les utilisateurs, les espaces de travail, les projets, les collections, les partages et les champs personnalisés (métadonnées) sont modélisés comme des ressources distinctes dans l’API V4. Comprendre leurs relations et leurs fonctionnalités au sein de l’application permettra de mieux saisir leur fonctionnement dans l’API V4.

Vue d’ensemble de l’API

L’API Frame.io V4 est conçue pour respecter les principes architecturaux RESTful et utilise des méthodes HTTP standard ainsi que des codes de réponse, associés à des URL uniques spécifiques à chaque ressource. Frame.io publie une spécification OpenAPI 3.0 pour son API V4, qui fournit des informations détaillées sur ses points d’entrée, ses paramètres de requête et ses réponses. La spécification OpenAPI peut être exploitée par divers outils tiers de génération de code afin de faciliter le développement rapide d’applications clientes.

Conventions relatives aux URL et aux chemins d’accès

Les chemins d’accès publiés dans la spécification OpenAPI reflètent généralement les relations de propriété et d’inclusion entre les ressources. Par conséquent, certains paramètres de requête (par exemple, les identifiants de compte, les identifiants de dossier, etc.) sont intégrés dans le chemin d’accès à la ressource. Bien que ces chemins d’accès soient conçus pour être prévisibles et faciles à comprendre, la structure de certaines URL renvoyées par les requêtes API (par exemple, les URL pré-signées pour charger des fichiers ou les liens d’affichage) est susceptible de changer et ne doit en aucun cas être générée directement par une application cliente.

Paramètres de requête

Les paramètres de requête qui déterminent le comportement de la pagination et l’inclusion facultative de ressources associées dans les objets de réponse sont définis comme un ensemble standard de paramètres de requête : include, page_size, include_total_count. Certaines requêtes peuvent prendre en charge des paramètres de requête supplémentaires spécifiques à cette ressource ou à cette opération.

GET https://api.frame.io/v4/accounts/{account_id}/folders/{folder_id}/children?&include=project&page_size=5&include_total_count=true

Payloads pour les requêtes et les réponses

Les payloads des requêtes et des réponses sont structurées sous forme d’objets JSON. Par conséquent, l’en-tête « content-type » d’une requête HTTP POST, PUT ou PATCH doit indiquer le type de média application/json. Lors de la création ou de la mise à jour de ressources, la propriété data de la requête doit contenir l’objet ressource. Les attributs de la ressource en cours de création ou de mise à jour sont contenus dans cet objet. De même, les réponses valides qui contiennent des ressources les fourniront dans la propriété data de la réponse.

Pagination

Les réponses susceptibles de renvoyer un grand nombre d’objets ressources (par exemple, des listes de dossiers ou de commentaires) sont paginées afin de réduire la latence des requêtes à mesure que l’ensemble de résultats s’étoffe. Cela signifie que la réponse à une requête peut contenir une seule « page » de résultats. Comme indiqué plus haut, un client peut choisir une taille de page spécifique, dans la limite de 100 éléments, en utilisant le paramètre de requête page_size lors de l’envoi de la requête. Si aucune valeur n’est spécifiée, la taille de la page sera fixée par défaut à 50 éléments. L’API V4 utilise un type de pagination appelé pagination basée sur un curseur et inclut, dans la propriété links de l’objet de réponse (voir l’exemple ci-dessous), un lien relatif contenant une chaîne de curseur opaque (les clients ne doivent pas tenter de construire cette chaîne eux-mêmes) dans le paramètre de requête after. Le client peut ainsi récupérer la page suivante de résultats (voir l’exemple de réponse ci-dessous) en effectuant des requêtes successives. À l’heure actuelle, l’API V4 ne prend en charge que la pagination unidirectionnelle.

{
    "data": [
        {
            "created_at": "2024-10-02T00:22:44.887775Z",
            "creator_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
            "file_size": 102432,
            "id": "df171f3e-c95f-4454-9071-825cd924b572",
            "media_type": "application/pdf",
            "name": "sample.pdf",
            "parent_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
            "project": {
                "created_at": "2024-08-21T17:45:41.881596Z",
                "description": "For demonstration purposes",
                "id": "976dd413-a92b-4af6-b465-98aded0174a8",
                "name": "Demo Project",
                "owner_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
                "root_folder_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
                "storage": 20881946,
                "updated_at": "2024-10-02T00:22:47.168489Z",
                "workspace_id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
            },
            "project_id": "976dd413-a92b-4af6-b465-98aded0174a8",
            "status": "created",
            "type": "file",
            "updated_at": "2024-10-02T00:22:44.927993Z"
        }
    ],
    "links": {
        "next": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/folders/e183c7ba-07d9-425a-9467-ebdf0223d9ce/children?after=g3QAAAACZAAGb2Zmc2V0YQVkAAR0eXBlZAANb2Zmc2V0X2N1cnNvcg%3D%3D"
    },
    "total_count": 21
}

Erreurs

En cas d’erreur, la propriété errors de l’objet de réponse contient un tableau composé d’un ou plusieurs objets d’erreur fournissant des détails sur la ou les erreurs survenues. À l’heure actuelle, l’API V4 ne prend pas en charge les opérations par lots ; il n’y a donc aucun cas où le client doit gérer des erreurs ou des succès partiels.

{
    "errors": [
        {
            "detail": "Unexpected field: foo",
            "source": {
                "pointer": "/data/foo"
            },
            "title": "Invalid value"
        }
    ]
}

Le tableau suivant répertorie les codes d’état couramment utilisés par l’API V4.

Authentification et autorisation

L’API V4 s’appuie sur OAuth 2.0 et le service Adobe Identity Management Server (IMS) pour authentifier un utilisateur (AuthN) et générer des jetons d’accès pour le compte de cet utilisateur. Un jeton d’accès doit être fourni avec chaque requête API via l’en-tête d’autorisation HTTP (c’est-à-dire l’authentification par jeton Bearer).

Versions et rétrocompatibilité

L’API Frame.io V4 n’est pas rétrocompatible avec les versions antérieures des API Frame.io et, en règle générale, ne peut pas être utilisée pour accéder aux ressources contenues dans les comptes hérités ni pour les mettre à jour, car les concepts et le modèle de données de la version V4 ont subi des modifications importantes. Par conséquent, les URI associés à l’API V4 comportent tous le préfixe de chemin /v4. Cependant, l’API V4 continue d’évoluer rapidement et il est possible que de nouvelles fonctionnalités nécessitent parfois des modifications importantes. Le plus souvent, Frame.io publie de nouveaux ajouts dans son API que nous considérons comme des fonctionnalités expérimentales pendant un certain temps, ce qui nous permet de recueillir les commentaires des clients et d’analyser les données d’utilisation. Conscients que la rétrocompatibilité est une préoccupation majeure pour les clients qui gèrent des intégrations de production nécessitant une disponibilité élevée, nous concevons l’API V4 de manière à prendre en charge un niveau supplémentaire de gestion des versions via un en-tête HTTP personnalisé. Cela permettra aux clients d’opter pour l’utilisation de points d’entrée expérimentaux, d’éviter les modifications rompant la compatibilité et d’offrir des garanties de rétrocompatibilité au sein de l’espace de noms de l’API V4. De plus amples détails seront communiqués prochainement. Pour l’instant, on peut considérer sans risque que la version initiale de l’API V4 est stable et qu’il faudra attendre un certain temps avant d’envisager d’y apporter des modifications qui entraîneraient une incompatibilité.

Limites de débit

Tous les appels à l’API V4 sont soumis à une limitation de débit, et chaque ressource et opération de l’API est configurée avec sa propre limite. Ces limites vont de 10 requêtes par minute à 100 requêtes par seconde. À l’heure actuelle, chaque limite est appliquée par utilisateur, mais les règles et les limites elles-mêmes sont susceptibles d’être modifiées.

L’API V4 utilise un algorithme de type seau percé pour la limitation progressive du débit, dans lequel les limites sont actualisées progressivement au cours de la fenêtre temporelle qui leur est allouée. En d’autres termes, il n’existe pas de seuil fixe au-delà duquel les limites sont réactualisées pour une ressource donnée (c’est-à-dire les stratégies d’application « fixes » et « à fenêtre glissante »). Au contraire, les limites restantes sont actualisées en permanence à un rythme qui dépend de la limite de la ressource et de la fenêtre temporelle. Les requêtes qui dépassent la limite de fréquence pour un point d’entrée donné échoueront et renverront une erreur HTTP 429.

La stratégie que nous recommandons pour gérer les erreurs 429 est généralement appelée « back-off exponentiel ».

Pour faire court :

• Lorsque vous recevez un code 429, attendez un moment (au moins une seconde) avant de réessayer d’envoyer la requête.
• Si un autre message 429 est reçu, augmentez de manière exponentielle, ou doublez au moins, le délai d’attente précédent jusqu’à ce que le fonctionnement normal reprenne.

Afin de déterminer les limites de débit applicables à une requête donnée, les clients peuvent consulter les en-têtes HTTP suivants renvoyés dans la réponse :

Détails de l’API

Le Guide de référence de l’API constitue la documentation de référence pour l’API V4, mais il est utile de bien comprendre la hiérarchie des ressources telle qu’elle est définie par l’API V4 avant d’envoyer vos premières requêtes.

Hiérarchie des ressources

Un compte est généralement associé à une organisation et constitue la ressource fondamentale qui détermine le type d’abonnement, la propriété du contenu, les rôles et autorisations d’utilisateurs ou d’utilisatrices, ainsi que l’organisation de l’espace de travail. Ainsi, l’URL de presque tous les points d’entrée de l’API V4 comprend un préfixe qui identifie le compte dans lequel se trouve la ressource. Les espaces de travail (anciennement appelés « Équipes » dans la version héritée de Frame.io) et les projets servent à organiser à la fois le contenu et les utilisateurs, notamment pour définir qui a accès à quel contenu.

La hiérarchie de base des ressources de contenu dans Frame.io est la suivante :

Chaque ressource chargée sur Frame.io est finalement représentée sous la forme d’un Fichier, tandis que les Dossiers et les Piles de versions sont des ressources de stockage qui servent de conteneurs et constituent la base d’un modèle de stockage hiérarchique prenant en charge les ressources versionnées. La plupart des utilisateurs connaissent déjà le principe de base d’un dossier dans Frame.io : il sert simplement de conteneur non ordonné pour d’autres ressources de stockage (considérées comme ses éléments enfants) et représente un nœud dans l’arborescence des dossiers. Chaque projet dispose d’un dossier racine unique (identifié par la clé root_folder_id), qui sert de racine à l’arborescence de dossiers dans laquelle se trouvent toutes les ressources du projet.

Une pile de versions est un ensemble ordonné de fichiers. Son ordre est strictement linéaire et détermine un numéro de version pour chacun de ses éléments enfants, mais les clients peuvent réorganiser les fichiers au sein de la pile de versions comme bon leur semble. À tout moment, un fichier reste un élément enfant, contenu dans exactement un seul dossier ou une seule pile de versions à un moment donné. De même, un dossier ou une pile de versions sera toujours un élément enfant d’un seul et même dossier (à l’exception du dossier racine du projet).

Pour plus d’informations sur la manière d’effectuer des opérations CRUD de base sur les fichiers et dossiers stockés dans Frame.io, consultez le Guide de référence de l’API. Pour l’instant, l’API V4 ne prend en charge les piles de versions que lors de l’affichage du contenu d’un dossier, mais des points d’entrée permettant de créer et de mettre à jour ces piles seront bientôt disponibles.

Les SDK

Des kits de développement logiciel (SDK) sont disponibles pour TypeScript et Python. Vous pouvez les installer à l’aide des commandes ci-dessous. La section « Référence des SDK » de la documentation contient des informations complètes sur les SDK Python et TypeScript.

TypeScript

npm i -s frameio

Afficher sur npm

Python

pip install frameio

Afficher sur PyPi