API Get Started

O que é uma API?

API é um meio pelo qual dois sistemas podem se comunicar. É o acrônimo de Application Programming Interface. Este conceito é muito amplo, e nasceu muito antes da própria web ou de padrões recentes como SOAP e REST. Os sistemas operacionais, como Windows e Linux, têm APIS com as quais nossos programas podem se comunicar.

O que é REST e API RESTFUL?

Representational State Transfer é um modelo utilizado para projetar arquiteturas de sistema distribuído, baseadas em comunicação via rede. Ele costuma ser aplicado ao protocolo HTTP, trafegando mensagens em JSON:

{
“hello”:”world”
}

APIs Restful são aquelas que seguem os preceitos Rest. Para projetar uma API RESTFUL de sucesso, e começar com o pé direito na primeira API, leia os passos abaixo, que te tornam um aprendiz de ninja REST!

Vamos começar?

Modelagem da regra: O que o cliente precisa?

Assim como qualquer projeto começamos entendendo a necessidade do nosso usuário/cliente.

Uma requisição REST é composta por uma URL, que é o endereço onde o cliente irá buscar informações ou realizar ações. É importante ter um padrão que o usuário possa entender com mais facilidade. Geralmente, o recurso indica uma coleção, por isso deve ser descrito no plural e, além disso, verbos não são utilizados em endpoint. No caso da TOTVS, o padrão é:

http://{{host}}/api/{{agrupador}}/{{versão}}/{{recurso}}

Os parâmetros de query são passados na própria URL e identificados pelo caractere “?”. Esses parâmetros são mais abrangentes, e são utilizados pelas camadas de regra de negócio para indicar uma informação extra no processo. No caso de um GET, eles podem indicar um filtro; no de um POST, podem indicar um contexto. Na TOTVS, padronizamos alguns parâmetros para o retorno de informações. Eles são:

Utilizado para paginação;

Para ordenar os registros na resposta;

Para dizer quais campos devem constar no retorno;

Para expandir subníveis da resposta.

O Response é o resultado do processo solicitado. No caso de um GET, é uma lista referente à coleção solicitada.

Para alguns verbos, como o DELETE, faz sentido a resposta estar vazia, pois com o HTTP Status adequado já conseguimos entender que o processo foi bem-sucedido. Na TOTVS, temos alguns padrões para facilitar tanto o desenvolvimento quanto o consumo das APIs.

Listas: Este padrão permite que o cliente entenda que ainda existem registros na base.

{
“hasNext”:true,
“items”:[...]
}

Erro: permite que o cliente interprete e mostre as mensagens de erro de maneira unificada nas APIs da TOTVS.

{
“code”:”FW001”,
“message”:”Registro já cadastrado”,
“detailedMessage”:”Este registro já foi cadastrado verifique os valores enviados”,
“helpUrl”:”http://totvs.help.com.br/registro”
}

O protocolo HTTP pede um Status para indicar o resultado do processo para o cliente, sem que este processe a mensagem por inteiro. Segui-lo é muito importante, pois facilita o processo para quem consome, possibilitando a criação de fluxo e tratativas para o cenário. A lista completa pode ser encontrada no link .

Família de status indicando sucesso.

Família de status indicando falha pelo usuário.

Família de status indicando falha pelo servidor.

Há diversos padrões para documentar uma API, além de várias maneira de disponibilizar estas documentações. Entre as práticas comuns estão a criação de um portal de referência de API e de um endpoint dentro do próprio software, expondo a documentação. Na TOTVS, adotamos o padrão Open API 3.0.

O repositório das documentações está disponível no GITHUB e também dispomos do portal de referência de API.

Para entender a documentação, os campos são definidos por alguns formatos de dados, tanto para o envio dos dados quanto para a resposta. Os mais comum são:

Lógico: True ou false

Número inteiro: valor numérico inteiro

Número: valor numérico

Texto: valor alfanumérico, também utilizado para datas e arquivos:

Data (E8601DAw.)

yyyy-mm-dd

Hora (E8601TMw.d)

hh:mm:ss.ffffff

Data e hora combinados (E8601DZw)

yyyy-mm-ddThh:mm:ss+|-hh:mm

Sua API está quase concluída!

Dúvidas?
Entre em contato conosco!

totvs.ryver.com
Fórum API