Boas Práticas para Desenvolvimento de APIs REST

Com a crescente utilização da tecnologia REST na construção de APIs de integração, implementação de arquiteturas baseadas em micro serviços e o uso de frameworks como Angular-JS, os desenvolvedores se deparam com uma infinidade de possibilidades para implementação da solução. A ausência de uma especificação bem definida e um padrão que atenderá todos os casos, costumam gerar várias discussões entre desenvolvedores e arquitetos, algumas delas até filosóficas, como por exemplo: Se ocorrer um erro de negócio, qual status HTTP retornar? HTTP 200 com uma mensagem ou código do erro? HTTP 500? HTTP 400?… Como definir as URIs dos serviços? Quando utilizar Query Parameter? Usar JSON ou XML? e por ai vai. Devido à essas questões, é muito comum encontrar abordagens diferentes em projetos da mesma empresa e isso acaba se tornando um grande problema, hora um faz de um jeito, hora de outro.

Esse post visa elencar algumas dicas baseadas nas experiências adquiridas durante o desenvolvimento de vários projetos utilizando essa tecnologia. Não se trata de um padrão formal, que deve ser seguido à risca, são apenas sugestões que com certeza irão ajudar no seu dia a dia.

Dica 1 – Requisitos fundamentais para API

Lembre-se que você está desenvolvendo uma interface que será utilizada por outro desenvolvedor, então, é importante tomar alguns cuidados:

  • possuir documentação adequada;
  • ser o mais simples e intuitivo possível (affordance), seja na URI, payload, request ou response;
  • deve-se levar em conta a experiência do usuário. Procurar seguir o padrão já utilizado pelo mercado, evitar “coisas” mirabolantes;
  • manter a padronização, nas URIs, tipo de retorno, etc.

Dica 2 – Padrões HTTP

REST é baseado no protocolo HTTP, é importante seguir os padrões definidos por ele e aplicá-los onde eles fazem sentido, por exemplo, nos status code de retorno de um método.

Dica 3 – Utilize JSON

Evite utilizar XML, eles são verbosos, difíceis de ler. Basta analisar o gráfico abaixo extraído do Google Trends. Nele fica claro o crescente interesse na utilização de APIs JSON frente a APIs XML.

comparativo_json_xml

fonte: http://www.google.com/trends/explore?q=xml+api#q=xml%20api%2C%20json%20api&cmpt=q

Dica 4 – URI, recursos

Um dos princípios fundamentais de REST é separar a API em recursos semânticos, que serão manipulados através de solicitações HTTP, e eles devem fazer sentido para os usuários da API.
A identificação do recurso deve ser um substantivo e não um verbo. Não há uma regra que diga se o recurso deve estar no singular ou plural, porém, o escolhido, deve seguir um padrão em toda a API. Exemplo de recursos em uma API disponibilizada em um domínio denominado “meudominioxpto.com”:

/cliente
/produto
/pedido

E como lidar com relações? Por exemplo, o telefone de um cliente.

/cliente/33/ telefone – manipular os telefones do cliente 33;
/cliente/33/ telefone/10 – manipular os telefones 10 do cliente 33.

Dica 5 – URI, versionamento

Procure sempre informar a versão da API na URI, mantendo a versão atual e uma versão posterior. Isso visa manter a compatibilidade de sua API.

v1/cliente
v2/cliente

Dica 6 – URI, escrita

Utilize o caracter “-” para separar palavras, alguns servidores ignoram “camelCase”. Isso facilitará a leitura.

v1/cliente-ativo
v1/produto-em-falta

Dica 7 – Verbos HTTP

Use o verbo correto para as operações de CRUD (Create, Read, Update e Delete):

tab_verbos_http

Dica 8 – Status code HTTP

O uso correto do status code facilita muito a vida dos clientes (consumidores) de sua API, utilize-os da maneira correta e padronizada.

tab_status_code

Dica 9 – Passagem de Parâmetros

Das seis maneiras de como enviar parâmetros para API REST, as mais mais utilizadas são: Path Parameters; Query Parameters; Header Parameters e Body Parameters. É uma boa prática utilizá-las da seguinte maneira:

tab_parametros

Dica 10 – Diversos

Outras dicas mais abrangentes, porém não menos importantes:

  • Negociação do conteúdo. Procure informar no header da mensagem o “Content-type” e “Accept” utilizados pelo serviço. Exemplo: “accept”:“application/json” e “contenttype”:”application/json”;
  • Padronização do formato de datas. Use o padrão ISO8601 para os formatos: Date/Time/Timestamp: 2015-05-10T06:06:06+00:0 ou 2015-05-10 (https://www.w3.org/TR/NOTE-datetime) e adicione no header o suporte a outras línguas. Exemplo: “Accept-Language”:”fr=CA, fr-PR”
  • Cache: Informe se o serviço deve ou não utilizar cache (http://www.mobify.com/blog/beginners-guide-to-http-cache-headers), exemplo: “cache-control”:”no-cache”. Tome cuidado com o Internet Explorer! No IE, para desativar o cache, a configuração é um pouco diferente dos demais browsers: “pragma”: “no-cache”

Por ANDRÉ AILTON DOS REIS

Arquiteto de Software, lidando com bits e bytes desde 1990. Músico, fotógrafo e aquarista nas horas vagas.

Postado em: 21 de janeiro de 2016

Confira outros artigos do nosso blog

[Webinar] Profile de aplicações Java com Oracle Mission Control e Flight Recorder

24 de julho de 2017

Danival Calegari

Criando Mocks de serviços REST com SoapUI

27 de junho de 2017

Monise Costa

Three laws that enable agile software development

09 de março de 2017

Celso Gonçalves Junior

Medindo performance de uma API REST

21 de fevereiro de 2017

Monise Costa

Deixe seu comentário