Guida introduttiva

Adobe Developer Console

Per utilizzare un’API di Adobe, il primo passaggio consiste nel creare un progetto in Adobe Developer Console. I progetti in Developer Console corrispondono a un’applicazione che stai sviluppando in modo che utilizzi l’API Frame.io Developer. Questo è diverso da un progetto in Frame.io.

Dopo aver creato un progetto in Developer Console, aggiungi l’API Frame.io.

Novità dell’API Frame.io V4 Developer

Proprio come l’app Frame.io è stata completamente trasformata per la versione 4, anche l’API V4 è stata riprogettata completamente. Sebbene alcuni concetti chiave rimangano simili alle versioni legacy, molti sono stati sostituiti o riprogettati per supportare flussi di lavoro di collaborazione e integrazioni più potenti. L’introduzione di un’API completamente nuova ha inoltre fornito l’opportunità per semplificare drasticamente le nostre operazioni e dare priorità ai flussi di lavoro cliente più importanti.

Nell’API V4, alcune risorse come le aree di lavoro (chiamate “team” nella versione legacy di Frame.io) sono state rinominate per corrispondere a Frame.io V4, mentre altre, ad esempio le “risorse” nella versione legacy, sono state rinominate per fare riferimento a entità di archiviazione specifiche (file, cartelle e stack di versioni) in modo da ridurre la confusione degli sviluppatori. Altre ancora, ad esempio i campi personalizzati e le condivisioni, sono completamente nuove. Tra gli altri cambiamenti sostanziali, abbiamo ridotto drasticamente la quantità di dati restituiti per impostazione predefinita per le richieste di risorse, rinominato alcuni nomi di proprietà nelle nostre risposte per essere più accurati e coerenti su tutta la superficie dell’API e siamo passati a un nuovo meccanismo di impaginazione basato su cursore. Pertanto, è importante rendersi conto che, ad eccezione dell’API Camera to Cloud (C2C), i client che si integrano con l’API legacy non sono compatibili con l’API V4.

Inoltre, alcune funzionalità sono ancora in fase di sviluppo e dovrebbero evolversi rapidamente in risposta ai casi d’uso reali e ai feedback dei clienti. Alcuni esempi includono la capacità di creare azioni personalizzate e stack di versioni. Se una funzionalità che era disponibile nell’API legacy non è presente, è molto probabile che esista un’alternativa o che sarà disponibile presto, ma ci piacerebbe conoscere la tua opinione al riguardo.

Prima di esaminare in dettaglio l’API V4, è utile comprendere i concetti fondamentali espressi nell’app Frame.io V4. Un buon punto di partenza è la knowledge base di Frame.io V4. Concetti come account, utenti, aree di lavoro, progetti, raccolte, condivisioni e campi personalizzati (metadati) sono modellati come risorse distinte nell’API V4. Comprendere le loro relazioni e le funzionalità nell’app è utile per capire come funzionano nell’API V4.

Panoramica dell’API

L’API Frame.io V4 è progettata per seguire i principi architetturali RESTful e utilizza metodi HTTP standard e codici di risposta insieme a URL unici specifici per le risorse. Frame.io pubblica una specifica OpenAPI 3.0 per l’API V4, che fornisce informazioni dettagliate su endpoint, parametri di richiesta e risposte. La specifica OpenAPI può essere utilizzata da vari strumenti di generazione di codice di terze parti per facilitare lo sviluppo rapido di applicazioni client.

Convenzioni per URL e percorsi

I percorsi URL pubblicati nella specifica OpenAPI riflettono in genere le relazioni di proprietà e contenimento delle risorse. Pertanto, alcuni parametri di richiesta (ad esempio ID account, ID cartella, ecc.) sono incorporati nel percorso della risorsa. Sebbene questi percorsi siano progettati per essere prevedibili e facili da comprendere, la struttura di alcuni URL restituiti dalle richieste API (ad esempio gli URL di caricamento pre-firmati o i link di visualizzazione) potrebbe cambiare e non deve mai essere composta direttamente da un’applicazione client.

Parametri di query della richiesta

I parametri di richiesta che controllano il comportamento della paginazione e l’inclusione opzionale di risorse correlate negli oggetti di risposta sono definiti come un set standard di parametri di query: include, page_size, include_total_count. Alcune richieste potrebbero supportare parametri di query aggiuntivi specifici per quella risorsa o operazione.

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

Payload di richiesta e risposta

I payload di richiesta e risposta sono entrambi composti come oggetti JSON e, di conseguenza, l’intestazione content-type di una richiesta HTTP POST, PUT o PATCH deve specificare il tipo di media application/json. Durante la creazione o l’aggiornamento di risorse, la proprietà data della richiesta deve contenere l’oggetto risorsa. Gli attributi della risorsa che viene creata o aggiornata sono contenuti in questo oggetto. Allo stesso modo, le risposte di operazione riuscita che includono risorse le forniranno all’interno della proprietà data della risposta.

Paginazione

Le risposte che potrebbero restituire un numero elevato di oggetti di risorsa (ad esempio elenchi di cartelle o commenti) vengono paginate per ridurre la latenza delle richieste quando il set di risultati diventa grande. Ciò significa che la risposta a una richiesta può includere solo una singola “pagina” di risultati. Come accennato sopra, un client può scegliere una dimensione di pagina specifica, fino a un massimo di 100 elementi tramite il parametro di query page_size quando effettua la richiesta. Se non specificato, la dimensione predefinita della pagina sarà di 50 elementi. L’API V4 utilizza una forma di paginazione nota come paginazione basata su cursore e include un link relativo nella proprietà links dell’oggetto di risposta (vedi esempio in basso) che contiene una stringa cursore opaca (i client non devono tentare di costruire questa stringa da soli) nel parametro di query after, che consente al client di recuperare la pagina successiva di risultati (vedi risposta di esempio sotto) effettuando richieste successive. Al momento, l’API V4 supporta solo la paginazione unidirezionale.

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
}

Errori

Nel caso in cui si verifichi un errore, la proprietà errors nell’oggetto di risposta conterrà un array di uno o più oggetti errore che forniscono dettagli sull’errore o sugli errori verificati. Al momento, le operazioni batch non sono supportate dall’API V4, quindi non ci sono casi in cui il successo parziale e gli errori devono essere gestiti dal client.

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

La tabella seguente elenca i codici di stato comuni utilizzati dall’API V4.

Autenticazione e autorizzazione

L’API V4 si basa su OAuth 2.0 e Adobe Identity Management Server (IMS) per autenticare un utente (AuthN) e generare token di accesso per conto di tale utente. È necessario fornire un token di accesso con ogni richiesta API tramite l’intestazione HTTP Authorization (ad esempio, autenticazione con token bearer).

Versioni e compatibilità con le versioni precedenti

L’API Frame.io V4 non è compatibile con le versioni precedenti delle API Frame.io e, in genere, non può essere utilizzata per accedere o aggiornare le risorse contenute negli account legacy poiché sono stati apportati dei cambiamenti significativi ai concetti e al modello dati V4. Di conseguenza, tutti gli URI associati all’API V4 includono un prefisso del percorso /v4. Tuttavia, l’API V4 continua a evolversi rapidamente ed è possibile che le nuove funzionalità possano occasionalmente giustificare modifiche non compatibili. Capiterà alquanto spesso che Frame.io rilascerà nuove aggiunte all’API che consideriamo sperimentali per un certo periodo di tempo, permettendoci di ricevere e rispondere ai feedback dei clienti e alle metriche di utilizzo. Sappiamo bene che la compatibilità con le versioni precedenti è una preoccupazione importante per i clienti che gestiscono integrazioni di qualità produttiva con requisiti di alta disponibilità. Stiamo progettando l’API V4 per supportare un livello aggiuntivo di controllo delle versioni tramite un’intestazione HTTP personalizzata al fine di consentire ai clienti di scegliere di utilizzare endpoint sperimentali, evitare modifiche che interrompono il funzionamento e fornire garanzie di compatibilità con le versioni precedenti all’interno dello spazio dei nomi dell’ V4. Forniremo altri dettagli, ma per ora possiamo affermare che il rilascio iniziale dell’API V4 è considerato stabile e che passerà del tempo prima di contemplare l’introduzione di modifiche non compatibili.

Limite di frequenza

Tutte le chiamate API V4 hanno un limite di frequenza e ogni risorsa e operazione API è configurata con un proprio limite. I limiti vanno da un minimo di 10 richieste al minuto a un massimo di 100 richieste al secondo. Attualmente, ogni limite viene applicato per utente, ma i criteri e i limiti stessi sono soggetti a modifiche.

L’API V4 utilizza un algoritmo di tipo “leaky bucket” per limitare progressivamente la frequenza. I limiti si aggiornano gradualmente durante l’intervallo di tempo assegnato. In altre parole, non esiste un concetto di cutoff netto dopo il quale i limiti si aggiornano per una risorsa specifica (ovvero strategie di applicazione “fisse” e a “finestra scorrevole”). I limiti rimanenti si aggiornano costantemente a un ritmo relativo al limite e all’intervallo di tempo di una risorsa. Le richieste che superano il limite di frequenza per un endpoint specifico non riusciranno e genereranno un errore HTTP 429.

La strategia consigliata per rispondere agli errori 429 viene solitamente chiamata “backoff esponenziale”.

In breve:

• Quando si riceve un errore 429, occorre attivare la pausa per un determinato periodo (almeno un secondo) prima di riprovare la richiesta
• Se si riceve un altro errore 429, occorre aumentare esponenzialmente (o almeno raddoppiare) il precedente periodo di attesa fino a quando non riprende il funzionamento normale

Per determinare i limiti di frequenza che si applicano a una particolare richiesta, i client possono ispezionare le seguenti intestazioni HTTP restituite nella risposta:

Dettagli dell’API

La documentazione definitiva per l’API V4 è la nostra guida di riferimento dell’API, ma conviene comprende bene la gerarchia delle risorse modellata dall’API V4 prima di inviare le prime richieste.

Gerarchia delle risorse

Un account è generalmente associato a un’organizzazione e rappresenta la risorsa fondamentale che determina un piano di abbonamento, la proprietà dei contenuti, i ruoli o le autorizzazioni degli utenti e l’organizzazione dell’area di lavoro. Di conseguenza, il percorso URL verso quasi tutti gli endpoint nell’API V4 include un prefisso che identifica l’account in cui risiede la risorsa. Le aree di lavoro (precedentemente chiamate “team” nella versione legacy di Frame.io) e i progetti sono utilizzati per organizzare sia i contenuti che gli utenti, nonché chi ha accesso ai vari contenuti.

La gerarchia di base delle risorse dei contenuti all’interno di Frame.io è la seguente:

Ogni risorsa caricata su Frame.io è rappresentata come un file, mentre cartelle e stack di versioni sono risorse di archiviazione che fungono da contenitori e forniscono le basi per un modello di archiviazione gerarchico che supporta risorse con controllo delle versioni. La maggior parte degli utenti conosce già il concetto di base di una cartella in Frame.io: funge semplicemente da contenitore non ordinato di altre risorse di archiviazione (modellate come suoi elementi figlio) e rappresenta un nodo all’interno dell’albero delle cartelle. Ogni progetto ha una cartella principale univoca (identificata dalla chiave root_folder_id), che funge da radice dell’albero delle cartelle in cui risiedono tutte le risorse del progetto.

Uno stack di versioni è un contenitore ordinato di file. Il suo ordinamento è strettamente lineare e determina un numero di versione per ognuno dei suoi elementi figlio, ma i client possono riordinare i file all’interno dello stack di versioni come preferiscono. Un file sarà sempre un elemento figlio (contenuto all’interno) di esattamente una cartella o uno stack di versioni in qualsiasi momento. Allo stesso modo, una cartella o uno stack di versioni sarà sempre un elemento figlio di esattamente una cartella (esclusa la cartella principale del progetto).

Consulta la guida di riferimento dell’API per maggiori dettagli sull’esecuzione di operazioni CRUD di base su cartelle e file archiviati in Frame.io. Attualmente, l’API V4 supporta gli stack di versioni solo quando elenca i contenuti di una cartella, ma gli endpoint per creare e aggiornare gli stack di versioni saranno disponibili a breve.

SDK

Per TypeScript e Python sono disponibili degli SDK. Puoi installarli utilizzando i comandi riportati di seguito. La sezione Riferimento SDK della documentazione contiene riferimenti completi per gli SDK Python e TypeScript.

TypeScript

$
npm i -s frameio

Visualizza su npm

Python

$
pip install frameio

Visualizza su PyPi