Edwin Khodabakchian, uma das principais pessoas por trás do produto Collaxa BPEL que posteriormente viu-se parte do núcleo de estratégia SOA da Oracle, tem trabalhado de forma independente por vários anos no Feedly que "combina o twitter e o Google Reader num formato semelhante ao de uma revista". Recentemente Edwin escreveu um cookbook baseado em suas experiências sobre as melhores práticas para a construção de Web Services baseados em JSON. Sem dúvida é um trabalho em andamento, mas até o momento as orientações incluem:
Fase 1 – Definir um recurso/serviço simples | Pegue um recurso de exemplo como informações do Cliente, modele ele como JSON. Construa um servlet simples onde PUT cria um novo Cliente, GET retorna as informações do cliente baseado em sua chave, DELETE remove o cliente e POST atualiza as informações do cliente. Tenha certeza que PUT retorna a informação correta sobre a URL do recurso recém criado. No nosso caso, temos um framework que faz o mapeamento de JSON para o nosso modelo em Java e utiliza Hibernate para persistir esse modelo numa base de dados MySQL. As coisas mais importantes para esta fase são a representação correta em JSON e a formatação simples e limpa da url base.
E:
Fase 3 – Realizar validações | Altere a implementação de seu serviço realizando algumas validações sobre os dados do recurso JSON que é recebido durante o PUT e o POST. Aprenda como utilizar os códigos de erro HTTP para definir e transferir informações sobre a exceção. Aprenda como tratar essas exceções do lado do cliente. O importante para esta fase é ter certeza que você conhece os códigos de erro HTTP, reutilize eles quando fizer sentido e crie novos que sejam compatíveis com HTTP quando necessário.
Até o momento existem 7 fases distintas que variam desde a primeira já mencionada até autenticação e ciclo de vida. É sempre bom ver orientações que são baseadas em experiências reais e Edwin tenta cobrir coisas que sem dúvida causaram problemas no passado como:
Existem centenas de bibliotecas que ajudam a abstrair o XMLHTTPRequest. Escolha uma que seja cross browser. Escolha uma transparente o suficiente que permita a visualização das operações GET, POST, PUT e DELETE que você está invocando.
Ou:
Definir a granularidade correta para um evento de negócio e codificar corretamente é difícil. Você pode ter que repetir algumas vezes até acertar. Meu conselho é evitar excesso de engenharia: mantenha as coisas o mais simples possível e refatore quando novos casos de uso sugirem.
É claro que existem referências a vários aspectos de REST que são reconhecidos pela maioria dos proponentes como:
Fase 5 – Utilizar caching | A infraestrutura da web oferece mecanismos de cache muito bons (informações sobre a última alteração, duração do cache, eTag). Aprenda sobre esses mecanismos e verifique se você consegue utilizar de forma a melhorar o desempenho e escalabilidade do seu serviço.
Edwin também cobre algumas abordagens altamente práticas que a princípio aparentam ir de encontro as próprias regras REST/HTTP:
Alguns servidores não permitem DELETE, neste caso você deve aprender como utilizar POST através de uma sobrecarga de método.
De acordo com Edwin, eles estão considerando abrir o código da infraestrutura utilizada no back-end. Até lá, a documentação para a API do FriendFeed está disponível. Com a popularidade da combinação JSON+REST em ascensão, a leitura e compreensão deste cookbook é muito interessante para desenvolvedores.