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:

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

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

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:

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 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.

Por exemplo, para criar um novo processo:

Para visualizar uma petição:

Para listar uma lista de remessas:

Para editar uma peça de um processo:

Para excluir um envolvido de uma petição:

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:

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.

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:

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

• @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.