Guia de introdução

Adobe Developer Console

O primeiro passo para usar uma API da Adobe é criar um Projeto no Adobe Developer Console. Projetos no Developer Console correspondem a um aplicativo que você está criando para consumir a Frame.io Developer API. Isso é diferente de um Projeto dentro do Frame.io.

Depois de criar um Projeto no Developer Console, adicione a API do Frame.io a ele.

Novidades na Frame.io V4 Developer API

Assim como o aplicativo Frame.io foi completamente transformado para a versão 4, a API V4 também foi redesenhada desde a base. Embora alguns conceitos principais permaneçam semelhantes às versões legadas, muitos foram substituídos ou redesenhados para oferecer suporte a fluxos de trabalho de colaboração e integrações mais avançados. A introdução de uma API totalmente nova também ofereceu a oportunidade de simplificar drasticamente nossas operações e priorizar fluxos de trabalho importantes dos clientes.

Na API V4, alguns recursos, como espaços de trabalho (anteriormente chamados de Equipes na versão legada do Frame.io), foram renomeados para corresponder ao Frame.io Versão 4, enquanto outros, como Ativos na versão legada, foram renomeados para se referir a entidades de armazenamento específicas (Arquivos, Pastas e Pilhas de versões) a fim de reduzir a confusão dos desenvolvedores. Outros, como Campos personalizados e Compartilhamentos, são totalmente novos. Entre outras mudanças substanciais, reduzimos drasticamente a quantidade de dados retornados por padrão em solicitações de recursos, renomeamos alguns nomes de propriedades em nossas respostas para que sejam mais precisos e consistentes em toda a superfície da API e mudamos para um novo mecanismo de paginação baseado em cursor. Assim, é importante entender que, com exceção da API Camera to Cloud (C2C), clientes que integram com a API legada não são compatíveis com a API V4.

Além disso, alguns recursos ainda estão em andamento e devem ser disponibilizados e evoluir rapidamente em resposta a casos de uso e feedback reais dos clientes. Exemplos incluem a capacidade de criar ações personalizadas e pilhas de versões. Se um recurso anteriormente disponível em nossa API legada parecer ausente, é bem provável que exista uma alternativa ou que ele esteja disponível em breve, mas gostaríamos de ouvir você sobre isso.

Antes de começar a usar a API V4, é útil entender primeiro os conceitos principais expressos no aplicativo Frame.io Versão 4. Um bom lugar para começar é a Base de conhecimento do Frame.io V4. Conceitos como Contas, Usuários, Espaços de trabalho, Projetos, Coleções, Compartilhamentos e Campos personalizados (Metadados) são modelados como recursos distintos na API V4, e compreender seus relacionamentos e recursos no aplicativo ajudará a entender como funcionam na API V4.

Visão geral da API

A API Frame.io V4 foi projetada para seguir princípios arquitetônicos RESTful e usa métodos HTTP e códigos de resposta padrão em conjunto com URLs exclusivas e específicas de recursos. O Frame.io publica uma especificação OpenAPI 3.0 para nossa API V4, que fornece informações detalhadas sobre seus pontos de acesso, parâmetros de solicitação e respostas. A especificação OpenAPI pode ser consumida por várias ferramentas de geração de código de terceiros para facilitar o desenvolvimento rápido de aplicativos cliente.

Convenções de URL e caminho

Os caminhos de URL publicados na especificação OpenAPI geralmente refletem relações de propriedade e contenção de recursos. Dessa forma, alguns parâmetros de solicitação (por exemplo, IDs de conta, IDs de pasta etc.) são incorporados no caminho do recurso. Embora esses caminhos tenham sido projetados para ser previsíveis e fáceis de entender, a estrutura de algumas URLs retornadas por solicitações de API, por exemplo, URLs pré-assinadas para fazer upload ou links de exibição, pode estar sujeita a alterações e nunca deve ser composta diretamente por um aplicativo cliente.

Parâmetros de consulta de solicitação

Parâmetros de solicitação que controlam o comportamento de paginação e a inclusão opcional de recursos relacionados em objetos de resposta são definidos como um conjunto padrão de parâmetros de consulta: include, page_size, include_total_count. Algumas solicitações podem oferecer suporte a parâmetros de consulta adicionais específicos daquele recurso ou operação.

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

Conteúdos de solicitação e resposta

Conteúdos de solicitação e resposta são compostos como objetos JSON e, portanto, o cabeçalho content-type de uma solicitação HTTP POST, PUT ou PATCH deve especificar o tipo de mídia application/json. Ao criar ou atualizar recursos, a propriedade data da solicitação deve conter o objeto de recurso. Os atributos do recurso que está sendo criado ou atualizado ficam contidos nesse objeto. Da mesma forma, as respostas bem-sucedidas que incluem recursos fornecerão estes dentro da propriedade data da resposta.

Paginação

Respostas que podem retornar grandes números de objetos de recurso, por exemplo, listagens de pastas ou comentários, são paginadas para reduzir a latência da solicitação à medida que o conjunto de resultados cresce. Isso significa que a resposta a uma solicitação pode incluir apenas uma única “página” de resultados. Como mencionado acima, um cliente pode escolher um tamanho de página específico, até o máximo de 100 elementos, por meio do parâmetro de consulta page_size ao fazer a solicitação. Se não for especificado, o tamanho da página será 50 elementos por padrão. A API V4 usa uma forma de paginação conhecida como paginação baseada em cursor e inclui um link relativo na propriedade links do objeto de resposta (veja o exemplo abaixo) que contém uma string de cursor opaca (os clientes não devem tentar construir essa string por conta própria) no parâmetro de consulta after, que permite ao cliente recuperar a próxima página de resultados (veja a resposta de exemplo abaixo) fazendo solicitações subsequentes. No momento, a API V4 oferece suporte apenas à paginação unidirecional.

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
}

Erros

Caso ocorra um erro, a propriedade errors no objeto de resposta conterá uma matriz de um ou mais objetos de erro que fornecem detalhes sobre os erros ocorridos. No momento, operações em lote não são compatíveis com a API V4, portanto não há casos em que sucesso parcial e erros precisem ser tratados pelo cliente.

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

A tabela a seguir lista códigos de status comuns usados pela API V4.

Autenticação e autorização

A API V4 depende do OAuth 2.0 e do Adobe Identity Management Server (IMS) para autenticar um usuário (AuthN) e gerar tokens de acesso em nome desse usuário. Um token de acesso deve ser fornecido com cada solicitação da API por meio do cabeçalho HTTP Authorization (ou seja, autenticação de Bearer token).

Versões e compatibilidade com versões anteriores

A API Frame.io V4 não é compatível com versões anteriores das APIs do Frame.io e, em geral, não pode ser usada para acessar ou atualizar recursos contidos em contas legadas, pois houve mudanças significativas nos conceitos e no modelo de dados da V4. Assim, os URIs associados à API V4 incluem todos um prefixo de caminho /v4. No entanto, a API V4 ainda está evoluindo rapidamente e é possível que novos recursos ocasionalmente justifiquem alterações incompatíveis. Mais comumente, o Frame.io lançará novas adições à API que consideramos experimentais por determinado período, permitindo-nos receber e responder a feedback de clientes e métricas de uso. Reconhecendo que a compatibilidade com versões anteriores é uma preocupação importante para clientes que gerenciam integrações com qualidade de produção e altos requisitos de disponibilidade, estamos projetando a API V4 para oferecer suporte a um nível adicional de versionamento por meio de um cabeçalho HTTP personalizado, permitindo que clientes optem por usar pontos de acesso experimentais, evitem alterações incompatíveis e tenham garantias de compatibilidade com versões anteriores dentro do namespace V4. Mais detalhes serão fornecidos em breve, mas, por enquanto, é seguro presumir que a versão inicial da API V4 é considerada estável e que levará algum tempo até considerarmos introduzir alterações incompatíveis.

Limitação de taxa

Todas as chamadas da API V4 têm limitação de taxa, e cada recurso e operação de API é configurado com seu próprio limite. Os limites variam de 10 solicitações por minuto até 100 solicitações por segundo. No momento, cada limite é imposto por usuário, mas as políticas e os limites estão sujeitos a alterações.

A API V4 usa um algoritmo “leaky bucket” de limitação de taxa progressiva, no qual os limites são atualizados gradualmente durante a janela de tempo atribuída. Em outras palavras, não existe o conceito de um corte rígido após o qual os limites são atualizados para um recurso específico, ou seja, estratégias de aplicação de “janela fixa” e “janela deslizante”. Em vez disso, os limites restantes são atualizados constantemente em um ritmo relativo ao limite e à janela de tempo de um recurso. Solicitações que excederem o limite de taxa de determinado ponto de acesso falharão com um erro HTTP 429.

Nossa estratégia recomendada para responder a erros 429 costuma ser chamada de “backoff exponencial”.

Em resumo:

• Ao receber um 429, pause por um período (pelo menos um segundo) antes de repetir a solicitação
• Se outro 429 for recebido, aumente exponencialmente, ou pelo menos dobre, o período de espera anterior até que o funcionamento normal seja retomado

Para determinar os limites de taxa aplicáveis a uma solicitação específica, os clientes podem inspecionar os seguintes cabeçalhos HTTP retornados na resposta:

Detalhes da API

A documentação definitiva da API V4 é o nosso Guia de referência da API, mas entender a hierarquia de recursos modelada pela API V4 será útil antes de emitir suas primeiras solicitações.

Hierarquia de recursos

Uma Conta geralmente está associada a uma organização e representa o recurso fundamental que determina um plano de assinatura, propriedade de conteúdo, funções/permissões de usuários e organização do espaço de trabalho. Assim, o caminho de URL para quase todos os pontos de acesso na API V4 inclui um prefixo que identifica a Conta na qual o recurso reside. Espaços de trabalho (anteriormente chamados de Equipes na versão legada do Frame.io) e Projetos são usados para organizar conteúdo e usuários, incluindo quem tem acesso a qual conteúdo.

A hierarquia básica de recursos de conteúdo dentro do Frame.io é a seguinte:

Todo ativo carregado no Frame.io é representado como um Arquivo, enquanto Pastas e Pilhas de versões são recursos de armazenamento que funcionam como contêineres e fornecem a base para um modelo de armazenamento hierárquico que suporta ativos versionados. A maioria dos usuários já está familiarizada com o conceito básico de uma Pasta no Frame.io: ela simplesmente serve como um contêiner não ordenado de outros recursos de armazenamento (modelados como seus tarefas derivadas) e representa um nó dentro da árvore de pastas. Todo Projeto tem uma pasta raiz única (identificada pela chave root_folder_id), que serve como a raiz da árvore de pastas na qual todos os ativos de um Projeto residem.

Uma Pilha de versões é um contêiner ordenado de Arquivos. Sua ordenação é estritamente linear e determina um número de versão para cada um de seus filhos, mas os clientes podem reordenar os Arquivos dentro da pilha de versões como desejarem. Um Arquivo sempre será filho de (contido em) exatamente uma Pasta ou Pilha de versões em determinado momento. Da mesma forma, uma Pasta ou Pilha de versões sempre será filha de exatamente uma Pasta, excluindo a pasta raiz do Projeto.

Consulte o Guia de referência da API para obter mais detalhes sobre como executar operações básicas de CRUD em Arquivos e Pastas armazenados no Frame.io. No momento, a API V4 oferece suporte a Pilhas de versões apenas ao listar o conteúdo de uma Pasta, mas pontos de acesso para criar e atualizar Pilhas de versões estarão disponíveis em breve.

SDKs

Há SDKs disponíveis para TypeScript e Python. Você pode instalá-los usando os comandos abaixo. A seção Referência do SDK da documentação tem referências completas para os Python e TypeScript.

TypeScript

$
npm i -s frameio

Visualizar em npm

Python

$
pip install frameio

Visualização em PyPi