Melhores práticas ao desenvolver API RESTful

Seu modelo de dados começo a se estabilizar, você já se sente em uma posição para disponibilizar-los através de uma API pública. Você começa a perceber que é difícil realizar mudanças significativas na sua API depois da disponibilização. A internet já conhece o que e uma API e o que ela oferece, mas ainda não existe um padrão bem consolidado de como sua API deve fornecer seus dados. Em qual modelo? Como deve autenticar? O que devo controlar?

Esse artigo e uma tradução e adaptação de: Best Practices for Designing a Pragmatic RESTful API

RESTful combinando recursos e ações através de URL’s

O padrão RESTful tem ganhado uma ampla adoção no ambiente web, eles foram introduzidos a primeira vez por Roy Fielding no Capitulo 5 da sua dissertação sobre arquitetura de software.

Os principais princípios do REST envolvem separar sua API em recursos lógicos. Esses recursos são manipulados através de solicitações HTTP onde o método(GET, POST, PUT, PATCH e DELETE) utilizado tem um significado específico.

Mas como eu posso separar esses recursos? Primeiramente esses recursos devem ser substantivos(nunca verbos) que possuem um significado dada a perspectiva da API. Embora seu modelos internos possam mapear ordenadamente os recursos, não e necessário um mapeamento um para um. O objetivo não e dar detalhes da implementação irrelevantes na sua API.

Depois de ter os seus recursos definidos, você precisa identificar quais ações se aplicam a eles e como os mapear na sua API. Os princípios RESTful fornecem estratégias para lidar com as ações de CRUD(Create, Read, Update e Delete) utilizando métodos HTTP mapeados da seguinte forma:

• GET /artigos: Retorna todos os artigos
• GET /artigos/12: Retorna o artigo com ID 12
• POST /artigos: Envia um artigo
• PUT /artigos/12: Atualiza o artigo com ID 12
• PATCH /artigos/12: Atualiza parcialmente o artigo com ID 12
• DELETE /artigos/12: Delete o artigo com ID 12

Algo importante sobre o REST e que você esta utilizando métodos HTTP para executar diversas funções diferentes no mesmo endpoint /artigos. Não há convenções de nomenclatura de método a serem seguidas e a estrutura de URL.

O endereço deve estar no singular ou no plural? A regra keep-it-simple também se aplica aqui. Embora pareça ser errado gramaticalmente utilizar o plural quando pode ser retornado apenas uma entidade, e importante manter o formato de URL consistente, por esse motivos e recomendado utilizar sempre o plural. Não ter que lidar com a pluralização estranha pode tornar a vida do consumidor da API melhor e é mais fácil para o provedor da API implementar se os endpoints seguirem um único padrão de nomenclatura.

Como lidar com relacionamentos? Se um relacionamento só pode existir dentro de um determinado recurso, os princípios RESTful fornecem um padrão. Vejamos isso como no seguinte exemplo: Um artigo possuem uma série de comentários. Esses comentários podem ser logicamente mapeados para o endpoint /artigos/:id/comentarios, da seguinte forma:

• GET /artigos/12/comentarios: Retorna todos os comentarios do artigo com ID 12
• GET /artigos/12/comentarios/2: Retorna o comentário com ID 2 do artigo com ID 12.
• GET /artigos/12/comentarios: Retorna todos os comentários do artigo com ID 12.
• POST/artigos/12/comentarios: Cria um comentário no artigo com ID 12.
• PUT /artigos/12/comentarios/2: Atualiza o comentário com ID 2 no artigo com ID 12.
• PATCH /artigos/12/comentarios/2: Atualiza parcialmente o comentário com ID 2 no artigo com ID 12.
• DELETE /artigos/12/comentarios/2: Deleta o comentário com ID 2 no artigo com ID 12.

Por outro lado, se um relacionalmente pode existir independentemente do recurso principal, faz sentido incluir um endpoint exclusivo para exposição desse recurso. No entanto, se o relacionamento for comumente solicitado junto com o recurso principal, a API poderia fornecer um endpoint que incorpore automaticamente a representação do relacionamento para evitar uma segunda chamada a API.

E as ações que não são operações de CRUD?

Aqui as coisas podem ficar bem confusas. Há várias abordagens:

1 — Reestruturar a ação para aparecer como um campo de um recurso. Isso funciona se a ação não utilizar parâmetros. Por exemplo, uma ação de ativação pode ser mapeada para um campo ativado booleano e atualizada via PATCH para o recurso.

2 — Trate-o como um sub-recurso com princípios RESTful. Por exemplo, a API do GitHub permite que você crie um star com PUT gists /:id/ star e não marque com DELETE /gists/:id/star.

3 — Eventualmente não será possível mapear um recurso para um padrão RESTFull sensato. Por exemplo, uma busca utilizando multiparâmetros, nesses casos um /pesquisa fará mais sentido. Lembre-se de sempre deixar a documentação clara sobre o objetivo do endereço.

SSL o tempo todo, em todos os lugares

Sempre use SSL. Sem exceções, sua API pode ser acessada de qualquer lugar pela internet. Nem todos esses lugares são seguros.Muitos não criptografam as comunicações, permitindo fácil espionagem ou representação se as credenciais de autenticação forem capturadas.

Outra vantagem de sempre usar o SSL é que as comunicações criptografadas simplificam os esforços de autenticação.

Documentação

Uma API é tão boa quanto a documentação. Os documentos devem ser fáceis de encontrar e publicamente acessíveis. A maioria dos desenvolvedores verificará os documentos antes de tentar qualquer esforço de integração. Quando os documentos estão escondidos dentro de um arquivo PDF ou requerem a assinatura, eles não são apenas difíceis de encontrar, mas também não são fáceis de pesquisar.

Os documentos devem mostrar exemplos de ciclos de solicitação / resposta completos. De preferência, os pedidos devem ser exemplos de pastagem — links que podem ser colados em um navegador ou exemplos de curvas que podem ser colados em um terminal. GitHub e Stripe fazem um ótimo trabalho com isso.

Uma vez que você divulga uma API pública, comprometeu-se a não romper as coisas sem aviso prévio. A documentação deve incluir quaisquer esquemas de desaprovação e detalhes em torno de atualizações de API visíveis externamente. As atualizações devem ser entregues através de um blog (ou seja, um changelog) ou uma lista de endereços (de preferência, ambos!).

Versionamento

Sempre versione sua API. O controle de versão ajuda a iterar mais rapidamente e impede que solicitações inválidas atinjam os pontos finais atualizados. Também ajuda a suavizar as principais transições de versão da API, pois você pode continuar a oferecer versões antigas da API por um período de tempo.