Em quase todos os projectos acabo por lidar com APIs sejam elas escritas por mim ou por terceiros. Neste artigo introduzo um conjunto de boas práticas a tomar em consideração durante o desenvolvimento de uma API.

O que é o REST / RESTFul?

REST (REpresentational State Transfer) é um conjunto de normas e boas práticas a seguir que garantem o desenvolvimento de sistemas escaláveis, resilientes e de fácil utilização destinados à comunicação entre maquinas. A web é um exemplo destes sistemas e talvez o maior. Milhões de páginas existem e são servidas em simultâneo para clientes de diversas plataformas sem problemas, tudo isto porque seguem as mesmas normas.

O REST não é uma invenção nova, o que é novo é a sua utilização e documentação, especialmente em APIs. O conceito de REST foi desenvolvido em conjunto com o protocolo HTTP como uma arquitectura a seguir para manter a coesão da informação.

Uma API RESTFul é aquela que de certo modo segue as normas REST, o “ful” na palavra indica-nos que não é 100% REST mas tenta ser o mais próximo possível. Na verdade desenvolver uma boa API é 20% de ciência e 80% de arte, mas isto não quer dizer que deveremos desprezar a ciência.

Nomes de Recursos e Acções

Nomear os recursos de forma apropriada é bastante importante porque é isto que garante a coesão e facilidade de utilização da API a longo prazo. Devemos sempre ter em atenção:

• Cada recurso da nossa API deve ter um URI único a identificá-lo e descrevê-lo de forma adequada (ex. http://api.dev/users);
• Os URIs devem ser previsíveis seguindo uma estrutura hierárquica: A hierarquia deverá ser definida pelas relações entre os dados disponibilizados (ex.  http://api.dev/tickets/1/attachments/2);
• Uma API deve ser desenhada para ser consumida: Os URIs deverão ter significado para quem os consome o que só acontece se forem definidos em torno dos requisitos das aplicações. Muitas vezes é difícil de prever qual o comportamento das aplicações logo uma API deverá ser continuamente melhorada analisando a forma como está a ser consumida;
• Deverá ser RESTful;

Primeiro que tudo devemos entender o que um recurso é uma entidade, normalmente aquilo a que chamamos um nome. Como tal users articles tickets seriam bons nomes de recursos, já send, delete, jump (verbos) não.

Numa API as acções (verbos) são sempre executadas sobre os recursos (nomes). Os métodos de HTTP definidos no RFC 7231 definem as acções que podemos realizar.

Como tal se quisermos listar (verbo) todos os utilizadores (nome), deveremos converter esta acção no seguinte pedido HTTP: GET http://api.dev/users. Para criar um utilizador deveremos executar: POST http://api.dev/users.

Para completar isto faço um resumo dos métodos de HTTP mais comuns, descrevendo-os com verbos que representam as acções a realizar sobre os recursos:

• GET: Obter, listar;
• POST: Publicar, criar;
• PUT: Actualizar (todo o recurso);
• PATCH: Emendar, remendar (uma actualização parcial a apenas algumas propriedades do recurso;
• DELETE: Apagar.

O que não fazer: Utilizar verbos no nome dos recursos, como por exemplo http://api.dev/update_users. Ao fazer isto a API deixa de ser RESTFul e não estamos a utilizar o HTTP da forma que ele foi desenhado. No HTTP todas as acções devem ser indicadas pelos métodos no cabeçalho do pedido.

No próximo artigo irei falar sobre Pluralização, Hierarquias e Relações.