Conceitos principais

Estrutura da API

A API do Frame.io é compatível com conceitos comuns como limitação de taxa, paginação para coleções de recursos, controle de versão e erros.Esta seção descreve as especificações de cada um.

Organização e estilo

A API é organizada em torno dos princípios comuns do REST.Todas as solicitações devem ser feitas por SSL.Todos os corpos de solicitação e resposta, incluindo erros, são codificados em JSON.

Salvo especificação em contrário, os métodos da API estão em conformidade com o seguinte:

• Propriedades sem valor usam null em vez de serem indefinidas * “Snake Case” é usado para nomes de atributo (por exemplo, first_name) * Os carimbos de data e hora são renderizados no formato ISO-8601 (por exemplo, 2016-02-03T16:38:46.985Z)

Convenções de caminho

Contas > Equipes > Projetos > Ativos > Comentários

Geralmente, os caminhos de recursos na API do Frame.io seguem o modelo hierárquico acima, limitando-se a um nível do elemento principal.Quando intuitivo, a API suporta caminhos de recursos autônomos para objetos que são estritamente pertencentes, logicamente falando.

Por exemplo, a API do Frame.io suporta ambos os caminhos a seguir:

• GET /accounts/:id/teams: retorna todas as equipes de uma conta.* GET /teams: retorna todas as equipes do usuário de chamada.* GET /teams/:id: retorna detalhes sobre uma equipe específica.

Outro exemplo: comentários não significam muito fora do contexto do ativo, então os métodos de criação e coleção de comentários ficam dentro do escopo do ativo.No entanto, ao atualizar ou excluir um comentário, o contexto do ativo não é tão significativo e é omitido do caminho do recurso:

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

Escopos

Ao recuperar um token via OAuth2.0 ou diretamente via Portal do desenvolvedor, todos os tokens de API devem ser associados a uma lista explícita de “escopos”, que se referem a uma combinação de um recurso (por exemplo, asset) e uma ação (por exemplo, create), e são expressos com notação de ponto.Por exemplo, um token com escopo asset.create seria capaz de criar novos ativos.

Se você está usando uma implementação com token de desenvolvedor, então os escopos são definidos e atribuídos ao próprio token de acesso.Se você está usando um aplicativo OAuth, os escopos são definidos para o aplicativo e, quando os usuários interagem com o aplicativo pela primeira vez, eles concordam em conceder ao aplicativo permissão para agir com os escopos solicitados.

Os escopos disponíveis para tokens de desenvolvedor e aplicativos incluem o seguinte (observe que alguns escopos não estão disponíveis para todos e são destacados quando há um problema).

Paginação

Métodos de API que retornam uma coleção de resultados são sempre paginados.Todos os métodos que esperam resultados paginados responderão aos seguintes parâmetros de consulta e retornarão os seguintes atributos de cabeçalho:

• next — o URL correspondente é o link para a próxima página.
• prev — o URL correspondente é o link para a página anterior.
• last — o URL correspondente é o link para a última página.

Observação: quando os links next e prev não estão presentes, isso indica que a primeira página retornada é a única página.