Conheça o Portal de Desenvolvedores da Sensedia

* escrito em parceria com Pablo Lobo

O Portal de Desenvolvedores é a porta de entrada ao desenvolvedor, onde terá acesso às documentações necessárias para realizar o consumo de uma ou mais APIs.

Entre suas funcionalidades estão:

• Exposição de documentações técnicas de APIs (swagger)
• Exposição de documentações funcionais
• Geração e gerenciamento das credenciais necessárias para o consumo de APIs
• Consulta a dashboards contendo informações referentes às APIs
• Consulta às perguntas e respostas mais frequentes de outros desenvolvedores
• Links importantes para documentações relacionadas ao desenvolvimento e boas práticas
• Canais de atendimento, se aplicável ao cliente

‍

Em seu estado inicial, todo Portal de Desenvolvedores conta com a identidade visual padrão da Sensedia, um usuário super admin e algumas páginas pré-configuradas. Para uma melhor apresentação e padronização, de acordo com os sites oficiais do cliente, é recomendada a customização. Nesse caso, são adicionadas as documentações e insumos das APIs, realizadas configurações de restrição de acesso e adequação à identidade visual do cliente.

Abaixo, vamos detalhar as etapas necessárias para se customizar um Portal de Desenvolvedores junto ao produto da Sensedia, exibindo assim suas funcionalidades e possibilidades de configurações e uso.

Documentação técnica

O termo documentação técnica diz respeito ao arquivo contendo o swagger de uma API. O Portal conta com uma página chamada API Browser já pré-configurada para exibição de documentações técnicas.

Toda documentação técnica deve ser disponibilizada no Portal através de um dos seguintes métodos:

• Trazida da API Platform utilizando a opção “show iterative documentation (swagger)”
• Fazendo o upload diretamente pelo Portal, através da tela Swagger 3. Por meio desse método, é possível realizar restrições de acesso de acordo com papéis/perfis
• Utilizando uma página com a biblioteca Redocly previamente configurada
  

Documentação funcional

Já o termo documentação funcional diz respeito a toda documentação contendo informações auxiliares ao swagger de uma API, como guia de primeiros passos, fluxo de autorização, códigos de retorno HTTP, fluxos de utilização, diagramas, SDKs e, se necessário, links para documentações externas.

Importante: uma documentação técnica sempre está associada a uma API específica, porém, uma documentação funcional pode tanto se referir a uma API específica quanto às APIs de um portal no geral.

O encarregado pela disponibilização de novas documentações funcionais no Portal pode ser alguém do time do cliente, preferencialmente com conhecimento de desenvolvimento front-end. No caso de clientes que possuam a contratação do Developer Experience, este profissional poderá disponibilizar tais documentações no Portal com o auxílio de um analista UX.

Restrições de acesso

Todas as restrições e concessões de acesso a conteúdos do Portal são feitas através de um sistema de papéis de usuário, que podem ser atribuídos a um ou mais usuários para definir seus níveis de acesso aos conteúdos do Portal. Inicialmente, o Portal conta com os seguintes papéis de usuário:

• Usuário anônimo: todo usuário que não esteja logado no Portal
• Usuário autenticado: um usuário que tenha cadastro e esteja logado no Portal
• Administrador: um usuário com privilégios de administração do Portal

‍

Novos papéis de usuário podem ser adicionados mediante a necessidade de cada cliente. Para que restrições de acesso possam ser implementadas, sempre que um papel de usuário for adicionado, deve-se também adicionar um grupo de acesso de mesmo nome associado a este papel.

Importante: o acesso de usuários não autorizados a APIs que deveriam ser restritas acarreta sérias implicações de segurança. Portanto, antes da disponibilização de qualquer documentação no Portal, as regras de restrição de acesso devem ser explicitamente definidas pelo cliente.

Internacionalização

O termo internacionalização (ou localização) diz respeito aos múltiplos idiomas nos quais um conteúdo está disponível. O Portal, por padrão, é disponibilizado nos idiomas português brasileiro (pt-br), inglês e espanhol. No entanto, é possível configurar outros idiomas mediante a necessidade de cada cliente.

Além disso, o próprio Portal conta com a funcionalidade de traduzir um conteúdo já existente, utilizando uma simples opção no painel de administrador pela opção traduzir.

Importante: a opção de tradução está disponível apenas para documentações funcionais. No caso de documentações técnicas, o ideal é que estejam todas no idioma inglês, por questões de boas práticas no desenvolvimento das APIs.

Customizações visuais

Para manter a coerência visual, de acordo com o manual da marca de cada cliente, é necessário que o Portal siga a identidade visual utilizada em outros sites e portais do cliente. Toda customização visual é realizada através do arquivo Custom CSS.

Mediante contratação da plataforma, é oferecida a todos os clientes a customização básica, contendo os seguintes elementos:

• Paleta de cores
• Tipografia (fonte, tamanho, peso e cor dos textos e títulos)
• Alteração do logo
• Alteração do ícone
• Adequação da página inicial do Portal

‍

Para que essa customização seja realizada em nível básico, é necessário que o cliente forneça um guia de identidade visual ou, ao menos, a paleta de cores, os arquivos de fonte, logos e ícones necessários.

Após a customização inicial, toda alteração visual posterior é de responsabilidade do cliente, ou, no caso de clientes que possuam a contratação das ofertas Sensedia como Developer Experience ou UX Avançado, este profissional poderá realizar eventuais novas alterações visuais.

Durante as customizações visuais do Portal, diferentes tipos de arquivos devem, preferencialmente, estar hospedados em diferentes locais:

• Arquivos de fonte devem ser utilizados através de uma CDN ou estar hospedados no navegador de arquivos do Portal
• Arquivos de imagem, incluindo logo e ícone, devem estar hospedados no navegador de arquivos do Portal
• Arquivos de vídeo devem estar hospedados externamente em serviço de streaming de vídeos
  

Se interessou pelo Portal de Desenvolvedores?

Essa é uma ferramenta cujo intuito é compartilhar e divulgar as documentações necessárias para utilização das APIs. É um canal exclusivo e apto para criação e gerenciamento de APPs e com foco em seus parceiros, contendo arquivos, documentos e especificações para uso das APIs, juntamente com possíveis regras de uso, SDKs, FAQ e demais informações necessárias e pertinentes para compreensão e realização do desenvolvimento.

Para se aprofundar ainda mais na importância do Portal de Desenvolvedores, clique aqui e confira mais um conteúdo que preparamos pra você!