API - Guia de Estilo

Check-list

466 views 26/03/2018 13/05/2019 admin 16

Este documento descreve uma lista de itens a serem verificados em sua API, visando maior padronização e governança.

( ) SDL está atualizada?

Garanta que seus projetos estão com a versão mais recente da SDL.

...
22.3.1
...

Justificativa: mantendo a versão da SDL atualizada você estará garantindo que o seu projeto irá gerar as documentações e códigos-fonte conforme a versão mais atualizada da plataforma.

( ) Domínio e serviço estão documentados?

Garanta que sua API possua:

Um nome para o Domínio

O nome do domínio deve ser composto de uma sigla que represente o produto e uma descrição do módulo que o domínio representa.

Exemplos: HCM – Painel de Gestão, ERP – Finanças, GAS – Portaria.

Um nome para o Serviço

Um nome que represente que serviço trata;

Exemplos: Fluxo de caixa, Folha de pagamento, Roteirizador de cargas.

Uma descrição para o Serviço.

Uma descrição sucinta do serviço abordando seu escopo e finalidade.

Exemplo de como informar nomes de domínio, serviço e descrição do serviço:

domain examples ("Exemplos")

"Serviço que demonstra a utilização do recurso de entidades e persistência de dados"
service todo_list_db ("Lista de Tarefas com Persistência") {
endpoints {
}
types {
}
entities {
...
}
}

Justificativa: os nomes amigáveis e documentação facilitam a identificação e pesquisa da API no portal de desenvolvimento e na listagem dos domínios e serviços dentro da plataforma.

( ) As primitivas estão documentadas?

Garanta que toda primitiva da sua API esteja documentada contendo:

  • uma descrição
  • a lista de Resources exigidos (permissões)
  • um link para a documentação (se aplicável)
"
Adiciona uma tarefa simples, onde titulo e descrição são os mesmos, com data para o **dia seguinte**.

### Resources: 

- res://senior.com.br/ecossistema/reference_app/actions/createShortTask

Para mais informações, consulte a [documentação](https://link_para_documentacao_complementar.com.br).
"
public action createShortTask {
...
}

As documentações são compatíveis com o padrão Markdown.

Justificativa: as documentações facilitam o uso e pesquisa pela API no portal de desenvolvimento.

 

( ) Está de acordo com a nomenclatura padrão?

Garanta que as primitivas de sua API seguem a nomenclatura padrão.

Justificativa: manter coerência nos formatos, métodos e parâmetros das APIs facilitam o consumo das mesmas por terceiros, permitindo reaproveitamento de código e de conhecimento.

( ) ServiceModel atualizado

Caso seu projeto utiliza o ServiceModel (generator.java.serviceModel=true), garanta que a propriedade generator.java.serviceModel.version no arquivo sdl.properties esteja com a versão mais recente.

generator.java.serviceModel.version=6.0.1

Caso o seu projeto esteja utilizando uma versão anterior e a nova versão possui quebra de compatibilidade (breaking changes), revise a documentação do CHANGELOG.

Justificativa: novos recursos e correções de bugs são liberados nas novas versões, garantindo compatibilidade com os demais serviços da plataforma.

( ) Está retornando os códigos HTTP corretos?

Caso seu projeto necessite lançar alguma Exception na implementação do Handler, é recomendado que a exception seja uma ServiceException, permitindo assim que o HTTP Status Code seja informado de acordo com a nomenclatura padrão e a estrutura de dados de retorno também seja padronizado.

Além disto, a mensagem da Exception deve ser internacionalizada.

throw new ServiceException(ErrorCategory.BAD_REQUEST, "Campo obrigatório", originalException);

Justificativa: o uso correto dos códigos de erro facilitam o consumo das APIs através de tecnologias e frameworks que normalmente já preveem formas de lidar com estes códigos.

( ) Está escondendo detalhes de implementação?

Os contratos de APIs devem ser agnósticos à tecnologia utilizada, sendo assim, deve-se verificar se o contrato definido está expondo algum detalhe que não deveria.

Exemplos:

 

Certo Errado Descrição
nome strNome Não expor um detalhe interno que é um String
expiraEm dtExpiraEm Não expor um detalhe interno que é um DateTime
tipo enumTipo Não expor um detalhe interno que é um Enumerador
documento recDocumento Não expor um detalhe interno que é Record
endereco entEndereco Não expor um detalhe interno que é Entidade

Justificativa: as terminologias de tecnologia e detalhes de implementação de uma API não devem “sujar” a linguagem de negócio exposta por uma API.

( ) Está usando verbo no infinitivo?

Os contratos de RPC APIs devem utilizar verbos no infinitivo (infinitive without to), ou seja, sem qualquer conjugação. Por exemplo, create, delete, validate, save, filter, calculate e etc.

Exemplos:

  • createCar, deleteCar, validateCar.

Justificativa: para padronizar a nomenclatura de operações disponíveis.

( ) Está traduzindo?

Os produtos Senior podem ser utilizados em diversos países, sendo assim, é importante que textos retornados pelas APIs sejam traduzidos. Por exemplo, mensagens de erro que são retornadas ao consumidor da API.

EXEMPLO

@Autowired
private TranslationHubApi translation;

...

TarefaEntity entidadeTarefa = tarefaRepository.findOne(request.id);
if (entidadeTarefa == null) {
throw new ServiceException(ErrorCategory.OBJECT_NOT_FOUND, translation.getString(TranslationConstants.ENTITY_NOT_FOUND));
}

Justificativa: habilitar que as APIs possam ser consumidas e entendidas por desenvolvedores de outros países ou idiomas.

Este artigo foi útil para você?