Conceptos clave

Estructura de la API

La API de Frame.io admite conceptos comunes como los límites de frecuencia, la paginación para colecciones de recursos, las versiones y los errores. En esta sección se describen los detalles específicos de cada uno.

Organización y estilo

La API está organizada en torno a los principios comunes de REST. Todas las solicitudes deben realizarse a través de SSL. Todos los cuerpos de solicitud y respuesta, incluidos los errores, están codificados en JSON.

Salvo que se especifique lo contrario, los métodos de API se ajustan a lo siguiente:

* Las propiedades sin valor utilizarán null en lugar de no estar definidas. * Se usa “Snake Case” para los nombres de atributos (por ejemplo, first_name). * Las marcas de tiempo se procesan en formato ISO-8601 (por ejemplo, 2016-02-03T16:38:46.985Z).

Convenciones de rutas

Cuentas > Equipos > Proyectos > Activos > Comentarios

Por lo general, las rutas de recursos en la API de Frame.io seguirán el modelo de jerarquía anterior, hasta un nivel de elemento principal. Cuando sea intuitivo, la API admite rutas de recursos independientes para objetos que son estrictamente propiedad, hablando lógicamente.

Por ejemplo, la API de Frame.io admite ambas rutas siguientes:

* GET /accounts/:id/teams: Devuelve todos los equipos para una cuenta. * GET /teams: Devuelve todos los equipos para el usuario que llama. * GET /teams/:id: Devuelve detalles sobre un equipo específico.

Otro ejemplo: Los comentarios no significan mucho fuera del contexto de su activo, por lo que los métodos de recopilación y creación de comentarios se encuentran dentro del ámbito del activo. Sin embargo, si se actualiza o elimina un comentario, el contexto del activo no es tan significativo y se omite de la ruta del recurso:

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

Ámbitos

Ya sea recuperando un token a través de OAuth 2.0 o directamente a través de Developer Portal, todos los tokens de API deben estar asociados con una lista explícita de “ámbitos”, que hacen referencia a una combinación de un recurso (por ejemplo, Asset) y una acción (por ejemplo, create), y se expresan con notación de puntos. Por ejemplo, un token con el ámbito asset.create podría crear activos nuevos.

Si está usando una implementación con un token de desarrollador, entonces los ámbitos se establecen y asignan al token de acceso en sí. Si utiliza una aplicación de OAuth, los ámbitos se definen para la aplicación, y cuando los usuarios interactúan con la aplicación por primera vez, aceptan conceder a la aplicación permiso para actuar con los ámbitos solicitados.

Los ámbitos disponibles para los tokens de desarrollador y las aplicaciones incluyen lo siguiente (tenga en cuenta que algunos ámbitos no están disponibles para todos, y se señalan cuando hay un problema).

Paginación

Los métodos de API que devuelven una colección de resultados siempre están paginados. Todos los métodos que esperan resultados paginados responderán a los siguientes parámetros de consulta y devolverán los siguientes atributos de encabezado:

• next: La URL correspondiente es el vínculo a la siguiente página.
• prev: La URL correspondiente es el vínculo a la página anterior.
• last: La URL correspondiente es el vínculo a la última página.

Nota: Cuando no están presentes los vínculos next ni prev, esto indica que la primera página devuelta es la única página.