Guía de introducción

Adobe Developer Console

El primer paso para usar una API de Adobe es crear un Project en Adobe Developer Console. Los Projects de Developer Console corresponden a una aplicación que se está creando para consumir la API de desarrollador de Frame.io. Esto es distinto de un Project dentro de Frame.io.

Después de crear un Project en Developer Console, añada la API de Frame.io.

Novedades de la API para desarrolladores V4 de Frame.io

Al igual que la aplicación Frame.io se ha transformado por completo para la versión 4, la API V4 también se ha rediseñado desde cero. Aunque algunos conceptos clave siguen siendo similares a los de las versiones heredadas, muchos se han sustituido o rediseñado para admitir flujos de trabajo de colaboración e integraciones más eficaces. La introducción de una API completamente nueva también ha brindado la oportunidad de simplificar drásticamente nuestras operaciones y priorizar flujos de trabajo importantes para los clientes.

En la API V4, se ha cambiado el nombre de algunos recursos, como Workspaces (denominados Teams en la versión heredada de Frame.io), para que coincidan con Frame.io Version 4. Otros, como Assets en la versión heredada, han cambiado de nombre para hacer referencia a entidades de almacenamiento específicas (Files, Folders y Version Stacks), con el fin de reducir la confusión de los desarrolladores. Otros recursos, como Custom Fields y Shares, son totalmente nuevos. Entre otros cambios importantes, hemos reducido drásticamente la cantidad de datos que se devuelve de forma predeterminada en las solicitudes de recursos, hemos cambiado el nombre de algunas propiedades en las respuestas para que sean más precisas y coherentes en toda la superficie de la API, y hemos adoptado un nuevo mecanismo de paginación basado en cursores. Por este motivo, es importante tener en cuenta que, con la excepción de la API Camera to Cloud (C2C), los clientes que se integran con la API heredada no son compatibles con la API V4.

Además, algunas funciones siguen en curso y se espera que evolucionen rápidamente en respuesta a casos de uso reales de clientes y a sus comentarios. Algunos ejemplos son la capacidad de crear acciones personalizadas y pilas de versión. Si parece que falta una función que estaba disponible anteriormente en nuestra API heredada, es muy probable que exista una alternativa o que esté disponible pronto, pero nos gustaría recibir sus comentarios al respecto.

Antes de empezar a trabajar con la API V4, conviene comprender primero los conceptos básicos que se expresan en la aplicación Frame.io Version 4. Un buen punto de partida es la base de conocimiento Frame.io V4. Conceptos como Accounts, Users, Workspaces, Projects, Collections, Shares y Custom Fields (Metadata) se modelan como recursos independientes en la API V4, por lo que comprender sus relaciones y capacidades en la aplicación ayuda a entender cómo funcionan en la API V4.

Información general de la API

La API V4 de Frame.io se ha diseñado para seguir principios de arquitectura RESTful y utiliza métodos HTTP y códigos de respuesta estándar junto con URL únicas y específicas de cada recurso. Frame.io publica una especificación OpenAPI 3.0 para nuestra API V4, que proporciona información detallada sobre sus puntos finales, parámetros de solicitud y respuestas. La especificación OpenAPI se puede consumir con diversas herramientas de terceros para generar código, con el fin de facilitar el rápido desarrollo de aplicaciones cliente.

Convenciones de URL y ruta

Las rutas URL publicadas en la especificación OpenAPI reflejan, por lo general, las relaciones de propiedad y contención de los recursos. Por ello, algunos parámetros de solicitud, como los ID de cuenta o los ID de carpeta, se insertan en la ruta del recurso. Aunque estas rutas están pensadas para ser predecibles y fáciles de entender, la estructura de algunas URL que devuelven las solicitudes de API (como las URL de carga con firma previa o los vínculos de visualización) puede cambiar y nunca debe componerse directamente desde una aplicación cliente.

Parámetros de consulta de solicitud

Los parámetros de solicitud que controlan el comportamiento de paginación y la inclusión opcional de recursos relacionados en los objetos de respuesta se definen como un conjunto estándar de parámetros de consulta: include, page_size y include_total_count. Algunas solicitudes pueden admitir parámetros de consulta adicionales específicos de ese recurso u operación.

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

Cargas útiles de solicitud y respuesta

Las cargas útiles de solicitud y respuesta se componen como objetos JSON y, por lo tanto, el encabezado content-type de una solicitud HTTP POST, PUT o PATCH debe especificar el tipo de medio application/json. Al crear o actualizar recursos, la propiedad data de la solicitud debe contener el objeto de recurso. Los atributos del recurso que se está creando o actualizando se incluyen dentro de este objeto. Del mismo modo, las respuestas correctas que incluyen recursos los proporcionarán dentro de la propiedad data de la respuesta.

Paginación

Las respuestas que pueden devolver un gran número de objetos de recurso (como listas de carpetas o comentarios) se paginan para reducir la latencia de la solicitud a medida que aumenta el tamaño del conjunto de resultados. Esto significa que la respuesta a una solicitud puede incluir solo una “página” de resultados. Como se ha mencionado anteriormente, el cliente puede elegir un tamaño de página específico, hasta un máximo de 100 elementos, mediante el parámetro de consulta page_size al realizar la solicitud. Si no se especifica, el tamaño de página predeterminado será de 50 elementos. La API V4 utiliza una forma de paginación conocida como paginación basada en cursores e incluye un vínculo relativo en la propiedad links del objeto de respuesta (consulte el ejemplo siguiente). Este vínculo contiene una cadena de cursor opaca, que los clientes no deben intentar crear por su cuenta, en el parámetro de consulta after, lo que permite al cliente recuperar la siguiente página de resultados mediante solicitudes posteriores (consulte el ejemplo de respuesta siguiente). Actualmente, la API V4 solo admite la paginación unidireccional.

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

Errores

En caso de que se produzca un error, la propiedad errors del objeto de respuesta contendrá una matriz con uno o más objetos de error que proporcionan detalles sobre los errores producidos. Actualmente, la API V4 no admite operaciones por lotes, por lo que no hay casos en los que el cliente deba gestionar éxitos parciales y errores.

1
{
2
    "errors": [
3
        {
4
            "detail": "Unexpected field: foo",
5
            "source": {
6
                "pointer": "/data/foo"
7
            },
8
            "title": "Invalid value"
9
        }
10
    ]
11
}

En la tabla siguiente se enumeran los códigos de estado habituales que utiliza la API V4.

Autenticación y autorización

La API V4 se basa en OAuth 2.0 y Adobe Identity Management Server (IMS) para autenticar a un usuario (AuthN) y generar tokens de acceso en nombre de ese usuario. Se debe proporcionar un token de acceso con cada solicitud de API mediante el encabezado HTTP Authorization, es decir, autenticación con token de portador.

Versiones y compatibilidad con versiones anteriores

La API V4 de Frame.io no es compatible con versiones anteriores de las API de Frame.io y, en general, no se puede usar para acceder a recursos incluidos en cuentas heredadas ni actualizarlos, ya que se han realizado cambios importantes en los conceptos y el modelo de datos de V4. Por este motivo, todos los URI asociados a la API V4 incluyen el prefijo de ruta /v4. Sin embargo, la API V4 sigue evolucionando rápidamente y es posible que, en ocasiones, las nuevas funciones justifiquen cambios importantes. Lo más habitual es que Frame.io lance nuevas incorporaciones a la API que consideremos experimentales durante un periodo de tiempo, lo que nos permite recibir y responder a los comentarios de los clientes y a las métricas de uso. Sabemos que la compatibilidad con versiones anteriores es una preocupación importante para los clientes que gestionan integraciones de calidad de producción con requisitos de alta disponibilidad, por lo que estamos diseñando la API V4 para admitir un nivel adicional de control de versiones mediante un encabezado HTTP personalizado. Esto permitirá a los clientes optar por usar extremos experimentales, evitar cambios importantes y ofrecer garantías de compatibilidad con versiones anteriores dentro del espacio de nombres V4. Próximamente se proporcionarán más detalles, pero por ahora se puede asumir con seguridad que la versión inicial de la API V4 se considera estable y que pasará algún tiempo antes de que contemplemos introducir cambios importantes.

Límites de frecuencia

Todas las llamadas a la API V4 están sujetas a límites de frecuencia, y cada recurso y operación de la API tiene configurado su propio límite. Los límites van desde un mínimo de 10 solicitudes por minuto hasta un máximo de 100 solicitudes por segundo. Actualmente, cada límite se aplica por usuario, pero tanto las políticas como los propios límites pueden cambiar.

La API V4 utiliza un algoritmo de “cubo con fugas” para aplicar límites de frecuencia progresivos, en el que los límites se actualizan gradualmente durante la ventana de tiempo asignada. Es decir, no existe un punto de corte fijo tras el cual se actualicen los límites de un recurso determinado, como ocurre con las estrategias de aplicación de “ventana fija” o “ventana deslizante”. En su lugar, los límites restantes se actualizan constantemente a un ritmo relativo al límite y a la ventana de tiempo del recurso. Las solicitudes que superen el límite de frecuencia de un punto final determinado fallarán con un error HTTP 429.

La estrategia recomendada para responder a errores 429 suele denominarse “espera exponencial”.

En resumen:

• Cuando reciba un 429, espere un periodo de tiempo (al menos un segundo) antes de reintentar la solicitud
• Si recibe otro 429, aumente exponencialmente, o al menos duplique, el periodo de espera anterior hasta que se reanude el funcionamiento normal

Para determinar los límites de frecuencia que se aplican a una solicitud concreta, los clientes pueden inspeccionar los siguientes encabezados HTTP devueltos en la respuesta:

Detalles de la API

La documentación definitiva de la API V4 es nuestra Guía de referencia de la API, pero conviene comprender la jerarquía de recursos modelada por la API V4 antes de enviar las primeras solicitudes.

Jerarquía de recursos

Una Account suele estar asociada a una organización y representa el recurso fundamental que determina el plan de suscripción, la propiedad del contenido, las funciones y los permisos de usuario, y la organización de Workspaces. Por ello, la ruta URL de casi todos los puntos finales de la API V4 incluye un prefijo que identifica la Account en la que reside el recurso. Los Workspaces (anteriormente denominados Teams en la versión heredada de Frame.io) y Projects se utilizan para organizar tanto el contenido como los usuarios, incluido quién tiene acceso a cada contenido.

La jerarquía básica de los recursos de contenido en Frame.io es la siguiente:

Todos los activos cargados en Frame.io se representan finalmente como Files, mientras que Folders y Version Stacks son recursos de almacenamiento que actúan como contenedores y sirven de base para un modelo de almacenamiento jerárquico compatible con activos versionados. La mayoría de los usuarios ya están familiarizados con el concepto básico de Folder en Frame.io: sirve simplemente como contenedor no ordenado de otros recursos de almacenamiento (modelados como sus elementos secundarios) y representa un nodo dentro del árbol de carpetas. Cada Project tiene una carpeta raíz única (identificada por la clave root_folder_id), que sirve como raíz del árbol de carpetas en el que residen todos los activos de un Project.

Un Version Stack es un contenedor ordenado de Files. Su orden es estrictamente lineal y determina un número de versión para cada uno de sus elementos secundarios, pero los clientes pueden reordenar los Files dentro de la pila de versión según sea necesario. Un File siempre será elemento secundario de exactamente un Folder o Version Stack, y estará contenido en él, en cualquier momento determinado. Del mismo modo, un Folder o Version Stack siempre será elemento secundario de exactamente un Folder, excepto la carpeta raíz del Project.

Consulte la Guía de referencia de la API para obtener más información sobre cómo realizar operaciones CRUD básicas en Files y Folders almacenados en Frame.io. Actualmente, la API V4 solo admite Version Stacks al enumerar el contenido de un Folder, pero próximamente estarán disponibles puntos finales para crear y actualizar Version Stacks.

SDK

Hay SDK disponibles para TypeScript y Python. Puede instalarlos con los comandos siguientes. La sección Referencia del SDK de la documentación incluye referencias completas de los SDK para Python y TypeScript.

TypeScript

$
npm i -s frameio

Ver en npm

Python

$
pip install frameio

Ver en PyPI