Concetti chiave

Struttura dell’API

L’API Frame.io supporta concetti comuni come limite della frequenza, paginazione per le raccolte di risorse, controllo delle versioni ed errori. Questa sezione descrive i dettagli di ciascuno di questi aspetti.

Organizzazione e stile

L’API è organizzata sulla base di principi comuni REST. Tutte le richieste devono essere effettuate tramite SSL. Tutti i corpi delle richieste e delle risposte, inclusi gli errori, sono codificati in JSON.

Se non specificato diversamente, i metodi API sono conformi a quanto segue:

• Le proprietà senza un valore utilizzano null anziché essere non definite * Lo “snake case” è utilizzato per i nomi degli attributi (ad esempio first_name) * Le marche temporali sono rese in formato ISO-8601 (ad esempio 2016-02-03T16:38:46.985Z)

Convenzioni dei percorsi

Account > Team > Progetti > Risorse > Commenti

In generale, i percorsi delle risorse nelle API Frame.io seguono il modello gerarchico indicato in alto, entro al massimo un livello padre. Se sono intuitivi, l’API supporta percorsi di risorse autonome per oggetti la cui proprietà è rigorosa dal punto di vista logico.

Ad esempio, l’API Frame.io supporta entrambi questi percorsi:

• GET /accounts/:id/teams: restituisce tutti i team per un account. * GET /teams: restituisce tutti i team per l’utente che effettua la chiamata. * GET /teams/:id: restituisce i dettagli di un team specifico.

Un altro esempio: i commenti non hanno molto significato al di fuori del contesto della risorsa, perciò i metodi di raccolta e creazione dei commenti si trovano nell’ambito della risorsa. Tuttavia, se si aggiorna o si elimina un commento, il contesto della risorsa non è altrettanto significativo e viene omesso dal percorso della risorsa:

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

Ambiti

A prescindere dal fatto che il recupero di un token avvenga tramite OAuth2.0 o direttamente tramite il Developer Portal, tutti i token API devono essere associati a un elenco esplicito di “ambiti”, che si riferiscono a una combinazione di una risorsa (ad esempio Asset) e un’azione (ad esempio crea). Sono espressi con la notazione a punti. Ad esempio, un token con ambito asset.create sarebbe in grado di creare nuove risorse.

Se stai utilizzando un’implementazione con un token sviluppatore, gli ambiti sono impostati e assegnati al token di accesso stesso. Se utilizzi un’applicazione OAuth, gli ambiti vengono definiti per l’applicazione e, quando gli utenti interagiscono con l’applicazione per la prima volta, accettano di concedere all’applicazione l’autorizzazione ad agire con gli ambiti richiesti.

Gli ambiti disponibili per i token sviluppatore e le applicazioni includono quanto segue (alcuni ambiti non sono disponibili per tutti e vengono segnalati in caso di un problema).

Paginazione

I metodi API che restituiscono una raccolta di risultati sono sempre impaginati. Tutti i metodi che prevedono risultati impaginati rispondono ai seguenti parametri di richiesta e restituiscono i seguenti attributi di intestazione:

• next: l’URL corrispondente è il link alla pagina successiva.
• prev: l’URL corrispondente è il link alla pagina precedente.
• last: l’URL corrispondente è il link all’ultima pagina.

Nota: se non è presente né il link next né il link prev, vuol dire che la prima pagina restituita è l’unica pagina.