API dos Serviços

API

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:

UseEm vez de
GET /processosGET /Processos

Utilize substantivos e não verbos. Por exemplo, para autuar um processo:

UseEm vez de
PUT /processos/{id}/autuacaoPUT /processos/{id}/autuar

Coloque os substantivos no plural. Por exemplo, para listar as petições:

UseEm vez de
GET /peticoesGET /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:

UseEm vez de
PUT /processos/{id}/analise-pressupostosPUT /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:

UseEm vez de
GET /processos/pecas?tipo=RE&meio=E&inicio=2016&final=2017GET /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étodoOperação
POSTCreate
GETRead
PUTUpdate
DELETEDelete

Por exemplo, para criar um novo processo:

UseEm vez de
POST /processosPOST /processos/criar

Para visualizar uma petição:

UseEm vez de
GET /peticoes/{id}GET /peticoes?id={id}

Para listar uma lista de remessas:

UseEm vez de
GET /remessasGET /remessas/listar

Para editar uma peça de um processo:

UseEm vez de
PUT /processos/{id}/pecas/{idPeca}POST /processos/{ìd}/pecas/{idPeca}/editar

Para excluir um envolvido de uma petição:

UseEm 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:

UseEm 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
GET /processos/{id}/partes?sort=-polo,+apresentacao

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
GET /peticoes?offset=10&limit=5

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.

StatusCodeDescrição
Success200, OkResposta padrão para requisições HTTP executadas com sucesso.
201, CreatedA requisição foi cumprida e resultou na criação de um recurso.
204, No ContentO servidor processou a requisição com sucesso, mas não é necessária nenhuma resposta.
Client Error400, Bad RequestA requisição não pode ser entregue devido à sintaxe incorreta.
401, UnauthorizedA requisição requer autenticação do usuário.
403, ForbiddenA requisição está correta, mas o usuário autenticado não tem autorização de executá-la.
404, Not FoundO recurso requisitado não foi encontrado.
409, ConflictIndica que a requisição não pôde ser processada por causa de conflito no pedido.
422, UnprocessableEntity 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 Error500, Internal ErrorIndica 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.

{
"httpCode": 404,
"errors": [{
"internalCode": 102,
"userMessage": "Classe requerida",
"moreDetails": "O campo [processo.classe] não foi informado em [preautuar]",
"targetName": "classe"
}, {
"internalCode": 103,
"userMessage": "Setor não pode ser nulo",
"moreDetails": "O campo [processo.setor] não foi informado em [preautuar]",
"targetName": "setor"
},
.
.
.
]
}

As propriedades retornadas na mensagem de erro representam:

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
GET /api/v1/processos/{id}
POST /api/v1/documentos/{id}/divisao

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:

Para o modelo (Command e DTO) as anotações usadas são: