Arquitetura de integração

Introdução

Antes de começar a fazer solicitações de API, você precisa entender a arquitetura básica das integrações C2C. (Não se preocupe. No próximo artigo, você vai trabalhar no terminal. Por enquanto, vamos abordar esses conceitos essenciais.)

O modelo de dados simplificado para sua integração será algo assim:

                                   ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 01 │ -> │ Project │
┌───────────┐    ┌──────────────┐  └───────────────────┘    └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘    └──────────────┘  ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 02 │ -> │ Project │
                                   └───────────────────┘    └─────────┘

Aplicativos OAuth

Sua integração é definida por um aplicativo OAuth, uma entidade registrada em nosso back-end que permite que seus dispositivos se autorizem no Frame.io usando o OAuth 2. Seu aplicativo OAuth define a estratégia de autorização para toda a sua integração. Todos os dispositivos que seus usuários conectam ao Frame.io vão autorizar pelo mesmo aplicativo OAuth (embora integradores com múltiplas linhas de dispositivos possam querer um aplicativo OAuth para cada uma).

Para integrações C2C, usamos um fluxo OAuth especializado, projetado especificamente para dispositivos com capacidades limitadas de interface.

Autenticação de dispositivos C2C

A API C2C é projetada para dispositivos com capacidades limitadas de interface. Esses dispositivos permitem que um usuário os conecte ao Frame.io exibindo um código de 6 dígitos, que o usuário então insere no site do Frame.io usando o próprio navegador.

Os dispositivos recebem um client_secret que deve ser fornecido ao nosso back-end para receber um código de autorização de 6 dígitos. Essa abordagem simplificada garante uma experiência de autenticação consistente e segura em todas as integrações C2C.

Modelos de dispositivos

O modelo de dispositivo configura como seu dispositivo se comporta ao interagir com o back-end C2C, incluindo quais recursos ele suporta. As seguintes configurações são definidas pelo modelo do seu dispositivo:

Os recursos compatíveis com o dispositivo podem mudar entre versões de firmware. Para garantir a compatibilidade com versões anteriores e uma experiência de usuário otimizada, a configuração do seu dispositivo é selecionada dinamicamente com base na versão do firmware detectada. Em um futuro próximo, uma integração poderá ter mais de um modelo de dispositivo. Qual modelo de dispositivo é usado será determinado comparando a versão de firmware do dispositivo com o requisito de versão mínima de firmware de um modelo de dispositivo específico.

Dispositivos de projeto e identificação

O ProjectDevice representa cada instância física de um dispositivo conectado ao Frame.io. Um ProjectDevice se identifica usando um valor de identificação único chamado client_id. Este valor deve ser algo que certamente não seja compartilhado entre dois dispositivos. Pode ser o número de série de um dispositivo ou uma string aleatória que o dispositivo gerou uma vez e salva. O client_id NÃO deve ser um valor que o dispositivo não possui, como o endereço MAC de um computador.

Nosso back-end monitora cada dispositivo de projeto e salva informações sobre ele, como a versão atual de firmware.

Cada ProjectDevice terá um Project específico do Frame.io associado e uma OauthAuthorization concedendo ao dispositivo acesso ao projeto e um conjunto de escopos detalhando o que um dispositivo pode fazer. Para mais informações sobre quais escopos estão disponíveis, consulte os guias detalhados sobre implementação de autenticação e autorização. O ProjectDevice é o que é retornado pelo ponto de acesso /me. Um Device pode ser vinculado ativamente a apenas um ProjectDevice por vez e, portanto, a um único Project por vez.

Versões do firmware

O dispositivo deve fornecer a versão atual do firmware com o cabeçalho HTTP x-client-version sempre que você chamar um ponto de acesso em https://api.frame.io. Os guias posteriores de API incluirão este cabeçalho em cada exemplo. Em algumas instâncias, nosso back-end deve classificar várias versões de firmware e, para compatibilidade, exigimos que os valores DEVEM ser uma versão semântica válida. Isso inclui valores como 0.1.2, 2.1.3-preview.01 e 2.1.3-preview.01+build_19770504.01, entre outros.

Um erro será retornado se os valores da versão do firmware não forem versões semânticas válidas. Sabemos que nem todas as integrações rastreiam o firmware usando controle de versão semântico e, nesses casos, pedimos que você mantenha o controle de uma versão semântica para fornecer ao nosso back-end para cada versão interna que criar.

Ao fornecer o cabeçalho, diferentes versões do seu firmware podem suportar recursos diferentes (e às vezes conflitantes) dentro do Frame.io.

Próximas etapas

É hora de fazer algumas chamadas de API! Vamos aprender como autenticar e autorizar com C2C. Siga o guia de configuração para começar.