Como a TOTVS desenvolve e provê informações sobre suas APIs

Apresentando o API Reference

Transformação Digital tem sido a buzzword da vez. Muitas empresas estão investindo tempo e dinheiro para materializá-la. E muito se tem falado sobre como é crucial iniciar uma jornada de Transformação Digital para manter a competitividade no atual cenário econômico.

Há vários exemplos de negócios revitalizados ou criados do zero utilizando os conceitos de Transformação Digital. Poderia repetir aqui a lista de empresas que causaram impacto na economia por pautar sua operação puramente na Internet, mas creio que os exemplos já são bem conhecidos. Empresas virtuais, lucros reais.

Por trás dessa disrupção no mundo dos negócios, há, certamente, uma grande contribuição da Tecnologia da Informação, que disponibiliza vários elementos para a construção de uma plataforma de negócios ágil e extremamente conectada. E entre esses elementos, um dos que tem tido grande relevância para a jornada de Transformação Digital são as APIs (claro que tinha que ter uma sigla no meio…). Sua relevância é tanta, que o termo API Economy surgiu para agrupar tudo o que diz respeito ao uso de APIs como estratégia de negócio.

API é a sigla, em inglês, para Application Programming Interface. No contexto atual, correspondem a endereços da Web que são acessados geralmente por programas de computador (mas se você for um desenvolvedor, com certeza já acessou uma API pelo browser), com o objetivo de executar uma tarefa ou obter dados.

Para viabilizar a integração entre negócios, as APIs precisam estar documentadas e disponíveis para uso. Uma das formas que as empresas têm usado para atingir esses dois objetivos são os portais de desenvolvimento (Dev Portals).

E assim como diversas empresas, a TOTVS desenvolveu e disponibilizou para o mercado e desenvolvedores o TOTVS API Reference. Um portal que permite conhecer em profundidade as APIs públicas da TOTVS, oferecendo aos interessados as informações necessárias para realizar integrações com os produtos da empresa.

As APIs apresentadas no portal, baseadas no estilo REST, são documentadas pelas áreas especialistas nos segmentos de negócios para os quais a TOTVS provê soluções. As documentações são armazenadas num repositório central, que é utilizado para publicar as informações exibidas no API Reference.

Interface do usuário

A interface do TOTVS API Reference foi desenhada seguindo práticas de UX e contando com a contribuição de vários desenvolvedores, inclusive de fora da TOTVS.

Acessando o endereço https://api.totvs.com.br, o usuário encontra a página principal, de boas vindas, onde é disponibilizada uma caixa de pesquisa, seguida de cards que agrupam as APIs por objetivo de negócio.

Figura 1 - Página inicial do TOTVS API Reference.

Os cards listam algumas APIs de cada grupo, mas o usuário pode ver a lista completa clicando no botão ver todos, na parte inferior do card.

Figura 2 — Detalhe de um card, com a lista de APIs e o botão “ver todos”.

Acionando o botão ver todos, o usuário é redirecionado para uma nova página, que lista as APIs relacionadas ao grupo. Outra forma de acessar esta página é através da caixa de pesquisa da tela principal.

Figura 3 — Tela listando as APIs do card Distribuição e Logística.

A lista também utiliza o formato de cards, onde cada um deles apresenta mais detalhes sobre as APIs, como versão, descrição, os produtos da TOTVS que as implementam e o agrupador ao qual pertencem.

Na lateral da página, encontram-se dois grupos de filtro — agrupadores e produtos — que permitem ao usuário refinar a pesquisa, clicando sobre os itens do grupo de filtro, sendo que mais de um item pode ser selecionado simultaneamente.

Figura 4 — Filtros laterais em ação, com destaque para o filtro de agrupadores.

Ao clicar em um dos cards de API, o usuário é direcionado para a página de detalhamento, que mostra diversas informações sobre a API selecionada. Outra forma de acessá-la é diretamente da página principal, clicando no nome da API listada no card.

Figura 5 — Tela de detalhes de uma API.

De forma geral, nesta página é possível ver:

• Nome e versão da API.
• Uma descrição geral da API e dos endpoints disponíveis.
• Link para o repositório onde se encontra o documento OpenAPI que define a API (ícone ao lado do título da API).
• Os produtos que implementam cada endpoint, incluindo a versão a partir da qual estão disponíveis.
• Os parâmetros que cada endpoint disponibiliza, com detalhes sobre o tipo de dado e sua obrigatoriedade.
• Exemplos de código para consumo dos endpoints nas principais linguagens de programação.
• As respostas esperadas para cada endpoint, com detalhes sobre o tipo de dado e disponibilidade em cada produto, bem como exemplos de retorno em formato JSON.

Vejamos com mais atenção alguns dos recursos citados.

É possível navegar entre os endpoints de uma API utilizando o menu lateral, que acompanha a movimentação da página. Logo, se o usuário quiser ver um endpoint que esteja no final da página, basta clicar no item do menu (a menos que queira exercitar os dedos e usar o scroll do mouse :-D).

Figura 5 — Menu lateral acompanhando a navegação da página.

Cada endpoint é descrito segundo a estrutura abaixo:

• Título.
• Método e URI.
• Descrição do endpoint.
• Parâmetros, que podem ser de path, de query ou de header.
• Corpo da requisição.
• Respostas previstas (responses), mostrando o status HTTP e o corpo do retorno.

Na área que mostra o método e a URI, encontramos um botão que permite copiar estas informações, o que é útil caso se queira utilizar o endpoint em uma ferramenta de teste de APIs. Logo abaixo, vemos uma lista de produtos nos quais a API foi implementada e a versão a partir da qual ela está disponível.

Figura 6 — Área da URI, com destaque para o botão Copiar e o indicador de produto e versão, mostrando que a API está disponível apenas no Protheus, a partir da versão 12.1.21.

A área de parâmetros do endpoint exibe o nome de cada um deles, bem como o tipo de dado e tipo de parâmetro (path, query ou header). Além disso, é possível saber quais parâmetros são requeridos pela API, graças à presença do texto required (em vermelho) junto à descrição do parâmetro.

Figura 7 — Seção URI Parameters.

A área das requisições e respostas é exibida como botões, que ao serem acionados, revelam os detalhes de cada parte. Desta forma, o usuário pode navegar rapidamente entre os endpoints da página e expandir, quando necessário, apenas os detalhes que lhe interessar.

Figura 8 —Seções Request e Responses como botões.

Quando se expande a área de request, são exibidos os atributos que podem compor o corpo da requisição. Da mesma forma como na seção URI Parameters, informações como nome, tipo de dado, descrição e se o atributo é requerido são exibidas.

Além disso, ao lado, são mostrados exemplos de código para se utilizar o endpoint. As linguagens de programação referenciadas até a elaboração deste artigo são JavaScript, TL++, Java e C#. Outras linguagens estão na lista para serem adicionadas, como, por exemplo, ABL e PHP.

Figura 9 — Detalhamento da seção Request, mostrando os atributos do corpo da requisição e exemplos de código para consumir o endpoint da API.

Note que os atributos podem variar, quanto à sua obrigatoriedade, dependendo do produto que implementa o endpoint. Quando houver mais de um produto implementando-o, será possível vê-los na parte superior da listagem dos atributos.

Figura 9 — Parte superior da área de atributos, quando mais de um produto implementa o endpoint.

Na área de responses, é possível ver detalhes de uma resposta específica, expandindo somente o item relacionado. Encontramos ali a descrição dos atributos presentes na resposta, bem como um exemplo, em formato JSON.

Figura 10 — Área de responses, com a resposta correspondente ao código de status 200 expandida.

Arquitetura do portal

Esta parte do artigo é para quem gosta de olhar debaixo do capô. Desenvolvedores e entusiastas da tecnologia, essa é pra vocês!

Além do frontend, escrito em Angular, a solução TOTVS API Reference também é composta de um backend, escrito em .NET Core (C#), que interage com uma instância do Elastic Search Engine, bem como com um repositório no GitHub, onde se encontram os documentos OpenAPI.

O caminho que uma API percorre até chegar ao portal é o seguinte:

• O desenvolvedor escreve o documento OpenAPI e, ao seu término, abre um pull request no repositório do GitHub.
• O conteúdo do pull request é verificado por um agente validador, escrito em JavaScript, que examina se o documento segue as orientações preconizadas no Guia de Implementação de APIs da TOTVS.
• Além da validação técnica, o documento OpenAPI também é submetido à uma validação de negócio, realizada por um comitê.
• Passando pelas validações técnicas e do comitê, o documento OpenAPI é incorporado a branch principal (master), com a aprovação do pull request.
• Uma trigger do GitHub, vinculada à aprovação de pull requests, solicita ao backend do TOTVS API Reference que atualize o índice do Elastic Search com o novo documento de API.
• Com o índice atualizado, a API já está disponível para consulta no portal.

Figura 11 — Diagrama arquitetural do API Reference.

Com exceção da criação da API e da aprovação do pull request, todo o processo é automatizado, dando uma enorme agilidade ao processo de publicação, além de garantir que as APIs desenvolvidas pelos diversos segmentos de negócio estejam aderentes aos padrões definido pela TOTVS.

Convém citar que o backend utiliza o pattern BFF (Backend for Frontend), de forma que o documento OpenAPI armazenado no ElasticSearch é transformado, antes de ser entregue ao frontend, para que a sua apresentação no portal seja otimizada.

Conclusão

As APIs são um importante componente para viabilizar a Transformação Digital nas empresas. Ao disponibilizá-las para uso e experimentação para o mercado e para desenvolvedores, aumentam-se muito as chances de surgirem novas formas de uso e novos produtos, baseados nas APIs. Ou seja, expor APIs é um caminho para fomentar inovação.

A TOTVS, como empresa que gera inovação, está trabalhando fortemente para inserir-se, bem como aos seus clientes, neste novo cenário proporcionado pela API Economy. E certamente, o TOTVS API Reference é apenas o primeiro passo nesta jornada.