Há uma série de discussões em torno do REST e das APIs web nas listas e fóruns de discussão, e na opinião de Oliver Wolf, consultor sênior na InnoQ, não há uma verdade absoluta. Foi assim que Wolf iniciou a sua palestra "O que deve e o que não deve ser feito em uma API Web", na conferência GOTO Berlin.
Não pense em termos de endpoints. A especificação SOAP possui uma fachada com um ponto de entrada único. Em contraste com a web, que possui vários pontos de entrada que são construídos a partir de relacionamentos e interconexões, tendo a hipermídia como um elemento crítico. Em vez de fazer com que a sua API se torne um buraco negro com apenas uma via de entrada, deve-se utilizar controles de hipermídia para vincular as suas representações de recursos, de modo que tenham significado para o seu público.
Não exponha o seu modelo de domínio em sua API. Um problema presente em vários modelos é que estes contêm somente dados, sendo carentes de todos os tipos de comportamento (chamados de modelos anêmicos). A exposição de um modelo como este acaba gerando recursos CRUD (Create, Read, Update, Delete). Isto não é necessariamente um ponto negativo, pois às vezes tudo o que se precisa é de uma API CRUD pura. Entretanto, um problema em se expor somente um modelo CRUD é que um cliente usando uma API precisa de muito conhecimento: quais ações podem ser executadas em quais recursos; em qual ordem fazer as coisas etc. Muita lógica está presente no cliente, gerando um acoplamento forte entre o cliente e o servidor.
Projete sua API além da intenção. Pense sobre o que o seu cliente quer e o que fará. Ocasionalmente isto requer um equilíbrio entre clareza e flexibilidade, o quão limpa e simples a sua API deve ser versus qual flexibilidade é necessária. Um modo flexível, porém mais imperativo de consultar quais são os clientes mais rentáveis, poderia ser assim:
GET /customers?sortBy=grossmargin&order=descending
Em contrapartida, um estilo mais declarativo que expõe a intenção, porém menos flexível, poderia ser assim:
GET /most_profitable_customers
A ideia central de Oliver aqui é pensar sobre o que um cliente precisa para usar a sua API, qual seria o seu objetivo e tentar adatá-la para este fim.
Não abuse dos verbos GET e POST. Basicamente significa que não se deve utilizá-los da forma errada e que violem a especificação HTTP. Deve-se, por exemplo, não utilizar os verbos GET e POST para deletar um recurso. Os verbos HTTP são definidos por uma razão, eles possuem qualidades complementares e ganha-se muito ao seguir a especificação. Utilizar os verbos transmite intenção, o que o cliente espera fazer e qual o comportamento o cliente pode esperar do servidor.
Não limite as suas opções de códigos de erro em 200 e 500. Utilize todo o espectro de códigos de erro, há 160 códigos de erro para se escolher e há um para quase todos os tipos de erro concebíveis. Utilizar o código de erro correto é chave para o tratamento adequado do erro no cliente.
Um problema comum é os servidores retornarem 200 (OK), embora tenha ocorrido um erro. Fingir que está tudo bem quando na verdade não está, nem sempre é uma boa ideia.
Não ignore o cache. Haverá caches envolvidos, sejam quais forem, e estes são uma parte muito importante da web. Auxilie os caches adicionando cabeçalhos de cache apropriados. Se, por exemplo, não quiser que o cache seja realizado, seja explicito e o desligue.
Uma das melhores formas de se controlar o caching é utilizar validadores, de preferência Etags, que permitem ao lado do servidor agir sobre dados arbitrários. Uma ETag é apenas um valor que o servidor gera e passa para o cache, e é posteriormente devolvido ao servidor pelo cache, que questiona o servidor sobre a recentidade do recurso.
Não obrigue versionamento. O que é considerado como uma alteração de um recurso, na maioria das vezes é de fato uma alteração na representação. O recurso continua sendo o mesmo e mantém a mesma URL, sendo assim evite versionar a URL. Em vez disso deve haver uma nova versão do tipo de media, adicionando-se v2, por exemplo:
Content-Type=application/vnd.company.v2+xml
Não utilize extensões na negociação de conteúdo. A forma adequada de se negociar sobre um formato de representação é através do uso do Accept e Content-Type no cabeçalho.
A GOTO Berling Conference 2013 foi a primeira conferência GOTO em Berlin, e reuniu 420 participantes e 80 palestrantes.