Se você está montando um serviço REST, pode ser uma boa ideia seguir essas quatro dicas para produzir serviços melhores e mais úteis.
1) Saiba usar corretamente os verbos HTTP
Quem requisitar acesso a sua API irá utilizar os verbos GET, POST, PUT, e DELETE. São opções universais, facilmente compreensíveis. Desde que você obedeça ao que se espera destes verbos com clareza:
- GET
- Lê um recurso específico ou uma coleção de recursos, sem alterá-lo de forma alguma.
- PUT
- Atualiza um recurso específico ou uma coleção de recursos. Outro uso aceitável é a criação de um recurso específico se o seu identificador for conhecido antecipadamente.
- DELETE
- Remover ou deletar um recurso específico baseado em seu identificador.
- POST
- Criar um novo recurso. Também pode funcionar como uma alternativa para outras operações que não se encaixem nas categorias acima.
2) Utilize nomes coerentes para recursos importantes
Trabalhar a hierarquia da URL que representa seus recursos é fundamental e torna mais fácil compreender o que determinado recurso representa, fornecendo contexto para as requisições e aumenta a compreensão de sua API.
Recursos são visualizados de forma organizada a partir de seus nomes, e quanto mais amigável suas URLs, mais amigável será sua aplicação.
Siga algumas regrinhas práticas e rápidas para o caminho da URL do seu recurso:
- Use identificadores ao invés de query strings.
- Bom: /users/12345
- Ruim: /api?type=user&id=23
- Melhore a natureza hierárquica da URL para representar uma estrutura.
- Projete para seus clientes, para seres humanos, não para os seus dados.
- Nomes de recursos devem ser substantivos. Evite utilizar verbos como nomes de recursos para não confundir com métodos.
- Não misture plural com singular nas URLs. Dê preferência ao plural, já que estamos falando de coleções aqui.
- Bom: /customers/33245/orders/8769/lineitems/1
- Ruim: /customer/33245/orders/8769/lineitem/1
- Utilize nomes simples para indicar coleções. O plural já insinua a metáfora do grupo, sem que você precise de nomes como “customer_list”, “customers_collection” ou “customers_group”.
- Utilize minúsculas nas URLs. Alguns servidores ignoram o case, então é melhor prevenir do que remediar.
- Se precisar separar palavras, utilize (‘_’) ou (‘-‘), mas seja consistente.
- Mantenha as URLs curtas o máximo que puder.
3) Use códigos de resposta HTTP para indicar status
Códigos de status de resposta fazem parte da especificação HTTP. Há um bom número deles para as situações mais comuns. Para que seu serviço REST abrace a especificação, sua API web deveria também retornar códigos relevantes de resposta HTTP.
Por exemplo, quando um recurso e criado com sucesso (a partir de uma requisição POST), a API deveria retornar o código HTTP 201.
Segue uma lista de sugestões dos códigos de resposta HTTP mais comuns. Você também pode consultar a lista completa na especificação oficial.
- 200 OK
- Código geral de resposta. Usado normalmente para indicar sucesso na operação.
- 201 CREATED
- Uma criação foi realizada com sucesso (seja via POST ou PUT). Especifique a Location no cabeçalho para conter o link para o recurso recém-criado.
- 204 NO CONTENT
- Também indica sucesso mas quando não é gerado conteúdo para o corpo da mensagem, geralmente utilizado para operações de DELETE ou PUT.
- 400 BAD REQUEST
- Erro genérico quando não foi possível cumprir uma requisição e é gerado um estado inválido. Erros de validação de domínio, dados perdidos etc são alguns dos exemplos para disparar este tipo de resposta.
- 401 UNAUTHORIZED
- Mensagem de erro que pode ser retornada para falhas de autenticação.
- 403 FORBIDDEN
- Código de erro para usuário autenticado mas sem autorização para realizar a operação ou acessar o recurso por alguma razão.
- 404 NOT FOUND
- Indica que o recurso solicitado não foi encontrado ou para mascarar um erro 401 ou 403 por razões de segurança.
- 405 METHOD NOT ALLOWED
- Utilizado para indicar que a URL solicitada existe mas o método HTTP utilizado não é aplicável. Por exemplo, utilizar um POST quando a API não oferece suporte para criação de recursos na forma desejada. O ideal é que o cabeçalho HTTP também retorne uma lista dos métodos suportados para orientar o usuário.
- 409 CONFLICT
- Sempre que um recurso causar conflito se a requisição for cumprida. Entradas duplicadas quando não for permitido ou a remoção de recursos bloqueados são alguns exemplos.
- 500 INTERNAL SERVER ERROR
- Nunca utilize esta mensagem de erro intencionalmente. Use apenas para erros que o usuário não pode corrigir no seu lado.
4) Ofereça suporte tanto para JSON quanto para XML
A menos que os custos sejam excessivos, tente oferecer suporte tanto para JSON quanto para XML. Permita que os usuários troquem entre eles usando o cabeçalho HTTP Accept ou apenas trocando a extensão de .xml para .json na URL.
Entretanto, lembre-se de que suporte a XML significa também utilizar schemas para validação, namespaces etc. A menos que seja exigido pela sua área de atuação, evite inicialmente oferecer suporte a toda essa complexidade. JSON foi projetado para ser simples, direto e funcional. Crie seu XML para se comportar da mesma forma, se conseguir.
Isso implica em tornar o seu XML de retorno parecido com JSON: simples e fácil de ler, sem que um schema ou um namespace estejam presentes – apenas dados e links. Se precisar de maior complexidade do que isso, o custo do XML pode subir muito.
Nos últimos anos, vem decaído o consumo de XML, mas ele ainda está presente. Lembrando também que JSON-Schema também oferece capacidades de validação como os schemas, se você precisar deste nível de complexidade.
