O que é uma API? 

Uma Interface de Programação de Aplicações é uma coleção de informações padronizadas estabelecida por um software que possibilita a utilização de suas funcionalidades por outros aplicativos. Com as informações persistidas em uma especificação de API, é possível enviar ou receber dados de uma aplicação sem que seja necessário entrar nos detalhes da implementação deste programa.

É de grande interesse para a TOTVS que aplicações externas consigam se comunicar com seus produtos de maneira facilitada. Por meio da implementação de uma API, é possível que outras aplicações obtenham dados internos dos produtos TOTVS, apenas enviando uma requisição HTTP para o endereço devidamente descrito na especificação da API.

Para descrever uma API, se faz necessária uma especificação padronizada. O padrão utilizado para a construção das APIs TOTVS é o OpenAPI 3.0, o qual descreve um formato para definição de toda a API. Essa especificação é que define como serão evidenciados os endpoints e seus métodos, parâmetros de operações de entrada e saída, métodos de autenticação, metadados (tais como informações gerais, contato, licença e termos de uso), entre outros.

Criação de uma API

<Tópico pendente de informação>

 As regras para o desenvolvimento de APIs estão especificadas no nosso Guia de Implementação de APIs.

Explicaremos mais o x-totvs. Mais detalhes sobre construção de APIs podem ser encontrados em Implementação de APIs com Mensagem Padronizada#Defini%C3%A7%C3%A3odaAPIeseusEndpoints

Todas as APIs já desenvolvidas podem ser encontradas em nosso repositório do GitHub.

 Retornar ao Fluxograma de Criação de Integrações

Diferenciação entre API e Schema

Uma API não deve ser confundida com um schema. As APIs são contratos responsáveis por definir os métodos e caminhos que permitem a comunicação entre dois pontos. São as APIs que trazem informações relevantes sobre as trocas de dados entre uma aplicação e um produto TOTVS, definindo os moldes das mensagens trafegadas. Já o schema é a mensagem padronizada propriamente dita. Traz consigo uma forma de apresentar dados e seus tipos, permitindo a posterior transmissão de informações. Definições mais apuradas sobre os schemas podem ser encontradas na documentação sobre as mensagens padronizadas TOTVS.

Anteriormente era possível que o schema fosse incluso diretamente na API, porém essa regra foi modificada. Para aprimorar a reusabilidade dos schemas, agora os arquivos JSON devem ser separados em API e JsonSchema. Esse modelo possibilita a utilização do protocolo transactions sem que haja a necessidade do desenvolvimento de uma API, caso essa configuração seja suficiente para suprir a necessidade e interesse do desenvolvedor.  Como vantagem adicional, uma mesma API pode ser utilizada de formas diferentes, alterando somente o schema o qual ela faz referência.

Para uma melhor apresentação visual das APIs, foi criado o portal API Reference, onde todas as APIs desenvolvidas pelos segmentos TOTVS e aprovadas pelo comitê podem ser encontradas.

A propriedade "x-totvs"

<Tópico pendente de informação>

A propriedade x-totvs nas APIs traz diferentes informações dependendo da seção em que ela está localizada no OpenAPI, porém com um objetivo em comum: armazenar dados pertinentes aos produtos TOTVS. São nas propriedades x-totvs ao longo do documento que são especificadas informações como: nome do produto ao qual se refere, segmento ao qual está vinculado, adapter atrelado, se determinado verbo está disponível, entre outros.

A propriedade x-totvs pode estar presente em diferentes seções do OpenAPI

Implementação de APIs com Mensagem Padronizada

x-totvs em diferentes partes do OpenAPI

• x-totvs dentro da "info":

  O exemplo a seguir é um trecho da API UnitOfMeasure v2.

  (...) "info": { "description": "API para informações de Unidade de Medida para Unidade de Medida TOTVS", "version": "2.000", "title": "UnitOfMeasure", "contact": { "name": "T-Talk", "url": "api.totvs.com.br", "email": "[email protected]" }, "x-totvs": { "messageDocumentation": { "name": "UnitOfMeasure", "description": "Cadastro de Unidade de Medida", "segment": "Serviços" }, "productInformation": [ { "product": "Protheus", "contact": "[email protected]", "description": "Cadastro de Unidade de Medida", "adapter": "QIES030.prw" }, { "product": "Logix", "contact": "[email protected]", "description": "Cadastro de Unidade de Medida", "adapter": "" } ] } } (...)

A propriedade "messageDocumentation" do "x-totvs" traz informações sobre a própria API.

• • name: título da API;
  • description: descrição da API;
  • segment: segmento da TOTVS pelo qual aquela API foi implementada.

 Já a propriedade "productInformation" traz informações sobre os produtos TOTVS.

• • product: produto ao qual aquelas informações do "productInformation" se referem;
  • contact: e-mail para contato com quem desenvolveu aquela API naquele determinado produto;
  • description: descrição da API para aquele determinado produto;
  • adapter: adapter que se comunica com aquela determinada API;
  • A propriedade "productInformation" poderia ter ainda a tag helpUrl, que contém um link para a documentação daquela API para aquele produto, caso haja.

• x-totvs dentro dos verbos dos "paths"

  O exemplo a seguir também é um trecho da API UnitOfMeasure v2.

  (...) "paths": { "/UnitOfMeasures": { "get": { "tags": [ "UnitOfMeasures" ], "summary": "Retorna lista de Unidade de Medida", "x-totvs": { "productInformation": [ { "product": "Protheus", "available": true, "note": "Este verbo esta disponivel com todos os parametros", "minimalVersion": "12.1.21" }, { "product": "Logix", "available": true, "note": "Este verbo esta disponivel com todos os parametros", "minimalVersion": "12.1.23" } ] } (...)

Diferentemente do x-totvs da "info",  a propriedade "messageDocumentation" não está presente nos x-totvs dos "paths".

Já a propriedade "productInformation" traz informações sobre os produtos TOTVS.

• • product: produto ao qual aquelas informações do "productInformation" se referem;
  • available: campo booleano que indicia de o verbo esta implementado no produto;
  • note: observações sobre o verbo referente ao produto, como regras específicas;
  • minimalVersion: a versão minima na qual o verbo foi implementado no produto.
    
    

 Retornar ao Fluxograma de Criação de Integrações

Identificar se o produto a ser integrado já está definido na documentação da API

O API Reference é um portal que obtém os dados do JSON da API e os transfere para uma interface visual, tornando a navegação pelas APIs mais atrativa aos usuários. Para identificar quais produtos estão adaptados a uma determinada API, basta acessar o API Reference e identificar quais os produtos que se encontram explicitados (como demonstra a animação abaixo).

No caso do exemplo acima, os produtos Protheus e Logix são os que estão configurados para a API em questão.

Como evidenciado no GIF o usuário pode, se preferir, acessar diretamente o arquivo OpenAPI e indentificar no próprio JSON se as tags x-totvs especificam o produto procurado.

 Retornar ao Fluxograma de Criação de Integrações

Editar "x-totvs" da API

Caso a API já exista, porém não para o produto desejado pelo usuário, significa que há necessidade de adaptar a API para que o produto em questão passe a ser especificado.

<Tópico pendente de informação>

Adicionar novo produto, especificação de adapters etc etc

deve ser adicionado no info, nos paths e também schema 

 Retornar ao Fluxograma de Criação de Integrações