Em um novo texto - The Good, the Bad, and the Ugly of REST APIs - George Reese apresenta algumas recomendações sobre boas e más práticas muito comuns no desenvolvimento de APIs REST.
Como boas práticas, Reese destaca os seguintes pontos:
- Mapear os dados de acordo com o consumidor, e não de acordo com o modelo de dados.
Os dados em sua API não devem ser representações altamente normalizadas do seu modelo interno de dados, e sim devem representar um modelo que faça sentido ao seu consumidor.
Isso é similar ao princípio em SOA de separar o modelo de dados das mensagens do seu modelo de dados interno.
- Mensagens de erros que façam sentido ajudam muito. Quando você está construindo uma API, isso é muito importante.
Pense sobre todos os erros que o usuário pode cometer quando estiver aprendendo a utilizar sua API.
Deve-se suportar e retornar mensagens de erros, as mais detalhadas possíveis, sobre o que foi feito de errado. Alguns bons exemplos podem ser encontrados nesta apresentação.
- Disponibilizar uma documentação sólida da API reduz a necessidade de ajuda externa.
Uma documentação sólida da API fará com que o usuário entenda os exemplos mais simples para iniciar o uso da mesma, e ainda cobrir casos mais complexos ajudando facilitando o entendimento de como utilizá-la em tarefas mais avançadas.
- Utilizar uma API de segurança apropriada. Reese comenta, por exemplo, que autenticação OAuth, utilizada frequentemente com REST, funciona bem quando a API suporta interação com um navegador, mas dificilmente será aplicada em casos de comunicação entre sistemas. Mais discussões sobre segurança em APIs REST podem ser encontradas em "RESTful API Authentication Schemes".
- REST é bom, SOAP é ruim. Reese diz que:
SOAP é absurdamente complexo de implementar e manter, principalmente se os consumidores são implementados em diversas linguagens diferentes.
Ele ainda afirma que:
JSON é bom, XML é ruim;
Então segundo Reese, REST utilizando JSON é melhor que SOAP com XML. Este assunto foi recentemente discutido por Gerald Loeffler em "Is REST Successful in the Enterprise?".
... sem contrastar e comparar tecnologias baseado puramente em suas características técnicas poderemos perder o rigor técnico que este tipo de avaliação requer... assim que as pessoas tornam-se imersas em uma única maneira de ver o mundo (você pode chamar isso de ideologia; por exemplo WS-* ou REST, ou ainda estaticamente tipado ou dinamicamente tipado), elas inevitavelmente irão enxergar isto como verdade absoluta - isso passa a ser uma verdade obvia. Mas na verdade isso é apenas um modo de ver e pensar sobre o que temos lá fora (com características e propriedades particulares - e por isso que (também) precisamos das discussões puramente técnicas). Infelizmente, em desenvolvimento de software, a verdade normalmente está sempre no ponto de vista de cada um e as discussões normalmente terminam com insultos aos outros: Eles "não entenderam nada".
As práticas ruins (e feias) identificadas por Reese incluem:
- Limitar o uso do sistema é algo terrível de se fazer.
Se você pensa em criar algum tipo de limitação no seu sistema, tenha certeza de utilizar algum sistema inteligente de detecção que a) detecte tráfego legítimo como testes ou consultas regulares e b) minimize o impacto negativo de falsos positivos. Evite limitações baseado em "suposições por experiências anteriores" e consulte os clientes que possivelmente serão impactados.
- APIs em modo de conversação são terríveis. Reese define que APIs em modo de conversação são aquelas APIs que requerem mais de uma chamada para realizar uma única e comum operação. Os detalhes do que realmente constitui esta conversação, obviamente, depende do que eventualmente as pessoas desejam fazer com a API.
- Retornar HTML como resposta. Reese sugere que a resposta de um serviço deve ser sempre um JSON/XML válido, mesmo quando não for possível conversar com o servidor da API.
Se o consumidor da API receber ALGUMA vez um HTML como resposta, algo está muito errado.
- Os efeitos colaterais dos erros 500 são infernais. Uma API deve sempre certificar-se de que as chamadas que geram erros 500 não alteram o estado dos dados no sistema - desfazem quaisquer alterações que possam ter ocorrido durante a execução anterior.
Em seu texto Reese oferece um conjunto de melhores práticas muito sólidas sobre a implementação de APIs REST, descrevendo não apenas prós e contras, mas também os porquês - os fundamentos do porque algumas coisas são boas ou ruins. Estas melhores práticas não são específicas sobre REST, elas não falam sobre o projeto de APIs REST, definição de recursos ou ainda sobre a escolha do mecanismo apropriado para passagem dos parâmetros - esta é uma discussão sobre o projeto de qualquer tipo de API.