Integrações

Páginas filhas
  • Guia de implementacao das APIs TOTVS

Versões comparadas

Versão antiga 104

changes.mady.by.user Luciano De Araujo

Gravado em

comparado com

Nova versão 105

changes.mady.by.user Luciano De Araujo

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

Criamos um comitê interno, formado com um integrante de cada seguimentosegmento, para discutir e garantir a execução dos padrões definidos neste documento.

Cada um dos membros deve obrigatoriamente ser incluído no pull request de novas APIs publicas e cada um deles é responsável por garantir a correta disseminação e implementação dentro de seu próprio time das APIs privadas.

SeguimentoSegmentoMembro
fluigFluig
Carlos Alberto De Souza Junior
Integração
Elvis Leonardo de Oliveira Brito
RM
Lucas Peixoto Sepe
Protheus
Caio Quiqueto Dos Santos
Datasul

Luciano De Araujo

...

  • Ao referenciar uma entidade na URL ela deve estar no plural. Ex. /users ao invés de /user;
  • Evite caminhos com mais de 3 parâmetros (além da versão da API), pois isso dificulta a leitura e normalmente indica um problema arquitetural;
  • O caminho deve apontar para um recurso e não para uma ação sobre a entidade, use os verbos HTTP para representar uma ação. Nos casos onde não exista um verbo apropriado a ação pode ser informada como parâmetro no caminho da URL ou na URL.
  • Ao utilizar Query Param com nome composto, é necessário a utilização de camelCase.
  • Utilizar camelCase também para nome de recursos que contenham mais de uma palavra, por exemplo, . Exemplos: orderItem, customerVendor, etc.

...


Bloco de código
languagejs
http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/v2/users

Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.

Informações
titlePolitica de depreciação.

A politica de depreciação deve definir o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e estará disponível. A politica é pode ser única para cada área de negócio mas deve estar documentada e evidente para o usuário final.

Quando alterar a versão?

O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.

Alterações que devem gerar uma nova versão "minor":

  • URIs foram removidas ou renomeadas;
  • Foram removidos campos do retorno de um endpoint;
  • Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
  • Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
  • Um novo endpoint foi adicionado a API.

Alterações que NÃO devem gerar uma nova versão "minor":

  • Um novo formato de retorno é suportado pelo endpoint;
  • Novas propriedades são retornadas na entidade de retorno do endpoint;
  • Novos parâmetros opcionais podem ser passados para o endpoint.

...