Search docs/

Layers API Hub

O Layers API Hub é a funcionalidade que permite que apps da Layers troquem informações de forma estruturada. Essa comunicação entre apps é feita usando actions, um protocolo que especifica o formato de comunicação entre os consumidores e provedores de informação. Existem dois tipos de comunicação possível no Hub de APIs: request & respond ou publish & subscribe.

Request & Respond

As intents do tipo request & responde são utilizadas para que um app que deseja consumir um determinado tipo de informação mapeado pela layers possam requisitar os registros relevantes para um app provedor apto a respondê-las. Esse é o método de comunicação que apps visualizadores usam para buscar informações em ERPs através da Layers.

Fluxo de Informação

Integrando sua Startup
O app consumidor representa apps que requisitam dados (ex: Notas Acadêmicas). Já o app provedor representa os apps que provê informações (ex: ERPs).
×

  • 1 - App consumidor requisita lista de provedores para a Layers

Como uma comunidade na Layers pode ter diversos apps provedores de uma determinada action na mesma comunidade é necessário especificar de qual dos provedores o app consumidor deseja requisitar as informações da action. Para descobrir quais são os apps disponíveis para responder dados de uma action o app consumidor deve chamar o endpoint /v1/services/discover/:action.

  • 2 - App consumidor requisita informações para a Layers

Uma vez que o app sabe qual de qual provedor ele pretende consumir os dados da action ele deve fazer uma requisição POST com payload no formato especificado pela docuemntação para a Layers.

  • 3 - Layers repassa requisição para o provedor especificado

Quando a Layers recebe a requisição do app consumidor ela adiciona as chaves context e secret à requisição e repassa essa requisição chamando o endpoint registrado no manifesto do app provedor para responder com actions do tipo solicitado.

  • 4 - Provedor retorna informações da action para a Layers

O app provedor retorna as informações no formato especificado pela documentação para a Layers.

  • 5 - Layers repassa os dados para o app consumidor

A Layers repassa a resposta para o app consumidor de dados no formato estabelecido pela documentação.

Publish & Subscribe

Para que um app consiga receber informações assim que elas são atualizados o app deve implementar actions do tipo PubSub. As intents de PubSub são usadas para que apps provedores de informação (publishers) como ERPs e sistemas de controle de acessos possam enviar atualizações em tempo real que a Layers devem repassar para apps que escutam determinada action (subscribers), como apps visualizadores.

Diferentemente das intents requests e responds, as intents publishes e subscribes devem ser usadas apenas para transmitir informação urgente como avisos que há novos registros acadêmicos, entradas e saídas ou cobranças disponíveis. Informações específicas sobre quais são os registros disponíveis e outros detalhes devem ser consumidas via requests e responds. Essa distinção existe porque assim se o envio ou recepção de uma mensagem do pubsub falhar ou for enviada em duplicata o app consumidor de informação pode continuar operando normalmente sem perder ou duplicar informações como ocorreria se dependesse apenas das mensagens. Quando um app que escuta uma mensagem receber essa mensagem deve chamar o provider para consumir as informações que foram criadas/atualizadas.

Fluxo de Informação

Integrando sua Startup
O app provedor é aquele que notifica a Layers de um dado que precisa de atenção urgente (ex: Sistema de controle de acessos notificando entrada de aluno). O app consumidor recebe a mensagem repassada pela Layers e decide como lidar com ela (ex: app Entrada e Saída notifica os responsáveis).
×

  • 1 - App provedor (publisher) publica um evento da action

Apps que produzem informações urgentes além de ter intents responds também terão intents publishes. Para publicar uma mensagem para a Layers o app deve chamar o endpoint POST /services/publish/:action. Se a intent de publish tiver uma payload ela deve ser enviada no corpo da requisição, se não o corpo deve vir vazio. A Layers responderá com status 201 confirmando que a mensagem foi recebida e será repassada.

  • 2 - Layers repassa a mensagem para o app consumidor (subscriber)

A Layers repassa os eventos recebidos com contexto adicional para os apps na comunidade configurados como subscribers da action recebida.

  • 3 - App consumidor requisita a intent de buscar dados atualizados relevante

Ao receber uma mensagem da Layers, o app subscriber deve chamar a action de buscar informações atualizadas para receber as informações atualizadas e processa-las conforme o necessário (mandar notificações, fazer atualizações, etc). As actions aqui serão do tipo Requests & Responds e devem ser getUpdatedAfter como as do sync para garantir que mesmo se o app não receber alguma mensagem ele ainda assim vai receber a informação atualizada quando for buscar as informações atualizadas desde a data que recebeu a última mensagem.