- Iniciando
- Documentação
Arquitetura
Políticas e Padrões
Infraestrutura
- Ecossistema
Ambientes
Integração Contínua
Monitoramento
Utilitários
Documentos
- Equipe
API dos Serviços
Em geral, microserviços são acessados usando REST sobre HTTP. Neste caso, conceitos do domínio são modelados como recursos, que são expostos pelos serviços para formar a sua API. Neste documento, apresentaremos o conjunto de práticas que devem ser aplicadas sempre que desejarmos adicionar um novo recurso à API de um serviço.
Nomenclatura
Atribua nomes que deixem claro o que os recursos representam. Manter a legibilidade do URI é importante, dessa forma busque denominações sugestivas que representem intuitivamente o que o recurso executa.
Utilize somente letras minúsculas. Por exemplo, para listar processos:
Use | Em vez de |
---|---|
GET /processos | GET /Processos |
Utilize substantivos e não verbos. Por exemplo, para autuar um processo:
Use | Em vez de |
---|---|
PUT /processos/{id}/autuacao | PUT /processos/{id}/autuar |
Coloque os substantivos no plural. Por exemplo, para listar as petições:
Use | Em vez de |
---|---|
GET /peticoes | GET /peticao |
Em nomes compostos, use hífen na separação das palavras (spinal-case). Não utilize preposições, conjunções ou artigos. Por exemplo, para analisar pressupostos de um processo:
Use | Em vez de |
---|---|
PUT /processos/{id}/analise-pressupostos | PUT /processos/{id}/analise-de-pressupostos |
Evite muitos níveis transversais em um URI com sub-recursos, pois isso aumenta sua complexidade e diminui sua legibilidade. Como regra geral, utilize no máximo três níveis e faça uso de query string para os demais casos. Por exemplo, para listar as peças de processos recursais, eletrônicos e autuados entre um período:
Use | Em vez de |
---|---|
GET /processos/pecas?tipo=RE&meio=E&inicio=2016&final=2017 | GET /processos/pecas/tipos/RE/meios/E/inicio/2016/final/2017 |
Use os métodos HTTP para as operações básicas de criação, leitura, alteração e remoção. Abaixo uma tabela de correspondência entre os métodos HTTP e as ações de CRUD utilizadas para manipulação dos recursos.
Método | Operação |
---|---|
POST | Create |
GET | Read |
PUT | Update |
DELETE | Delete |
Por exemplo, para criar um novo processo:
Use | Em vez de |
---|---|
POST /processos | POST /processos/criar |
Para visualizar uma petição:
Use | Em vez de |
---|---|
GET /peticoes/{id} | GET /peticoes?id={id} |
Para listar uma lista de remessas:
Use | Em vez de |
---|---|
GET /remessas | GET /remessas/listar |
Para editar uma peça de um processo:
Use | Em vez de |
---|---|
PUT /processos/{id}/pecas/{idPeca} | POST /processos/{ìd}/pecas/{idPeca}/editar |
Para excluir um envolvido de uma petição:
Use | Em vez de |
---|---|
DELETE /peticoes/{id}/envolvidos/{id} | POST /peticoes/{id}/envolvidos/{id}/excluir |
Para filtrar oleções retornadas por recursos, utilize unicamente a query string para todos os campos, assim você desacopla os clientes da estrutura da URI. Por exemplo, para filtrar as peças de um tipo específico em determinado processo:
Use | Em vez de |
---|---|
GET /processos/{id}/pecas?tipo={tipoPeca} | GET /processos/{id}/pecas/tipos/{tipoPeca} |
Para ordenar uma coleção retornada pela execução de um recurso, utilize na query string um parâmetro “sort”, atribuindo-lhe uma lista com os múltiplos campos da ordenação. Para determinar se a ordenação será ascendente ou descendente, use os sinais de “+” ou “-“, respectivamente. Por exemplo, para ordenar a lista de partes de um processo descendente por polo e ascendente por apresentação:
Use |
Para paginar uma coleção de retorno do processamento de um recurso, use “limit” e “offset” como parâmetros na query string. Os valores padrão do “limit” e “offset” são 20 e 0, respectivamente. Por exemplo, para listar as cinco próximas petições, começando pela décima:
Use |
Formato dos Erros
Deve-se retornar o código de status HTTP adequado para cada operação realizada sobre um recurso. A tabela seguinte apresenta detalhes sobre o uso correto de alguns desses códigos de status HTTP.
Status | Code | Descrição |
---|---|---|
Success | 200, Ok | Resposta padrão para requisições HTTP executadas com sucesso. |
201, Created | A requisição foi cumprida e resultou na criação de um recurso. | |
204, No Content | O servidor processou a requisição com sucesso, mas não é necessária nenhuma resposta. | |
Client Error | 400, Bad Request | A requisição não pode ser entregue devido à sintaxe incorreta. |
401, Unauthorized | A requisição requer autenticação do usuário. | |
403, Forbidden | A requisição está correta, mas o usuário autenticado não tem autorização de executá-la. | |
404, Not Found | O recurso requisitado não foi encontrado. | |
409, Conflict | Indica que a requisição não pôde ser processada por causa de conflito no pedido. | |
422, Unprocessable | Entity Indica que o servidor reconhece o conteúdo da requisição, mas foi incapaz de processar as instruções contidas nela. Esse código também é utilizado para erros de validação dos dados de entrada do serviço REST. | |
Server Error | 500, Internal Error | Indica um erro do servidor ao processar a solicitação. |
Quando um erro ocorre, a prática REST espera o envio de um HTTP status code na resposta que classifique a causa da falha. As boas práticas sugerem o reuso dos códigos da tabela de status code da especificação HTTP sempre que possível. Dentro do conjunto de HTTP status code existentes, constam abaixo os que devem ser retornados caso ocorram problemas na execução dos serviços disponibilizados pela API do STF Digital.
Apenas o status code não é suficiente para deixar claro ao usuário a causa do problema no processamento da sua requisição. Para tornar mais legível, e até mesmo útil, a mensagem de erro deve trazer informações mais relevantes. O modelo adotado na API deverá ser retornado como JSON e terá a seguinte estrutura.
{ |
As propriedades retornadas na mensagem de erro representam:
- httpCode: corresponde ao HTTP status code retornado na resposta da requisição.
- errors: corresponde a uma lista de erros que ocorreram na requisição
- internalCode: código de erro interno específico da aplicação. Apresenta o código de erro conforme dicionário de erros mapeados no desenvolvimento da aplicação (refletem a camada de domínio). Para situações em que o erro não estiver mapeado será igual ao httpCode.
- userMessage: mensagem com informação inteligível ao usuário final.
- moreDetails: campo reservado para informações de cunho técnico que auxiliarão os desenvolvedores na resolução de problemas vinculados ao erro do processamento. Pode ser apresentado via link para entrada no dicionário de erros.
- targetName: campo ao qual esse erro se aplica. Ajuda a identificar qual campo causou um erro.
Versionamento
Conforme orientações encontradas em White House Web API Standards devemos sempre versionar uma API antes de sua liberação. O versionamento pela URL é utilizado por APIs populares como as do Atlassian, Facebook, LinkedIn e Twitter. Essa estratégia, apesar de semanticamente incorreta, é a mais fácil de usar e evita problemas como, por exemplo, os vinculados ao uso de cache pela aplicação.
Embora tenhamos a intenção de abrir nossa API, dentro de uma estratégia de dados abertos, não há planos de curto e médio prazo para exposição pública da API do STF Digital. Assim, para mantermos o alinhamento com as boas práticas de mercado, podemos adotar o versionamento via URL, colocando nos endpoints a versão um (v1) como padrão, conforme exemplos abaixo
PUT /api/v1/remessas/{id}/preautuacao-originario |
A estratégia de versionamento definida aqui deverá ser aplicada a todas as URL’s como pré-requisito para exposição pública da API do STF Digital.
Documentação
A documentação de uma API é essencial para facilitar o seu entendimento e a sua utilização. Dessa forma, a documentação de uma API deve ser informativa, sucinta e de fácil leitura para que outros desenvolvedores possam usá-la sem problemas.
Uma boa documentação começa por um bom código. Boas decisões de design ajudam na hora de documentar a API, assim obedecer aos padrões de codificação tende a tornar consistentes o comportamento da aplicação e facilitar a sua documentação.
Para documentar a API do STF Digital utilizaremos o Swagger, que pelas anotações utilizadas nos Controllers, Commands e DTOs disponibilizará páginas Html com a documentação da API possibilitando, inclusive, testes rápidos dos serviços disponibilizados.
No Controller serão utilizadas as seguintes anotações:
- @Api – Utilizada para documentar o RestResource;
- @ApiOperation – Descreve uma operação ou recurso HTTP;
- @ApiParam – Documenta o parâmetro de entrada de uma operação ou recurso HTTP.
Para o modelo (Command e DTO) as anotações usadas são:
- @ApiModel – Usada para descrever uma classe do modelo;
- @ApiModelProperty – Descreve uma propriedade dentro da classe do modelo.