API REST Design: 7 dicas essenciais

API REST design em sua melhor versão

*atualizado em 31 de março de 2020

REST API Design nada mais é do que criar uma interface com regras bem definidas, disponibilizadas para que você possa interagir com um sistema e obter suas informações ou realizar operações. É como expliquei lá nos artigos sobre O que são APIs: sua interface deve funcionar como um garçom em um restaurante: receber seus pedidos e devolver recursos (ou pratos), sem que os clientes precisem visitar a cozinha para pegar o prato lá.

Neste post, conheceremos algumas dicas para criar um projeto melhorado e padronizado do que chamamos de uma verdadeira API no padrão RESTful.

E, claro, é sempre bom considerar que ao projetar seu REST API, você também precisa ter em mente quem o utilizará, como será utilizado dentro de sua estratégia e também como será exposto ao mundo. Este raciocínio, colocando o API em um lugar privilegiado em seu planejamento, é chamado API First.

Usar substantivos e não verbos

Uma das grandes falhas de padronização ao criar APIs RESTful estão relacionadas ao padrão dos endpoints criados (URLs de acesso aos serviços). O padrão RESTful exige que sejam utilizados substantivos e não verbos ou nomes de métodos. Por exemplo:

/getAllCustomers/criateNewCustomer/deleteCustomer

Estas são formas incorretas de nomenclatura, que se assemelham às funções de alguma linguagem de programação orientada a objetos. Em vez disso, para o Design mais apropriado, use substantivos, como por exemplo:

/clientes/clientes/563

Usar corretamente os métodos HTTP

O princípio fundamental do REST é separar seu API em recursos lógicos. Estes recursos são manipulados usando solicitações HTTP com métodos GET, POST, PUT e DELETE.

Por exemplo, quando você faz uma solicitação ao recurso /customers/563 usando o método GET, você está solicitando que um cliente específico com o código 563 seja recuperado.

Da mesma forma, quando você faz a mesma solicitação (ou seja, no ponto final /clientes/536) usando o método DELETE, você estará realizando uma exclusão de cliente específica, código 563.

Usar nomes no plural

O nome do ponto final deve estar no singular ou no plural?

Esta é uma questão que normalmente gera muita discussão no RESTful API Design.

Em geral, cabe a você escolher. Em particular, prefiro nomes no plural, pois eles indicam um conjunto de características (como no caso dos clientes, acima). No entanto, uma coisa é certa: não misture os pontos finais no singular e no plural.

A recomendação é que você simplifique e use todos os nomes no plural.

Usar subrecursos para relacionamentos

Há situações em que um recurso está relacionado a outro. Isto é comum quando há uma hierarquia de objetos e recursos.

Por exemplo, se fosse um API que retorna dados estatísticos sobre a geografia de um país, poderia haver sub-recursos para estados dentro do país e municípios dentro dos estados.

Quando aplicável, utilizar sub-recursos nos pontos finais.

Por exemplo, a requisição

GET /customers/231/projetos/

deve retornar à lista de projetos do cliente 231. E a requisição

GET /customers/231/projetos/4

deve retornar ao projeto nº 4 do cliente 231.

Não mudar de estado com o método GET

Ao realizar operações que mudam o estado de um objeto, usar os métodos POST, PUT e DELETE.

O método GET, por ser intuitivo pelo nome, deve retornar apenas uma versão lida do recurso.

O HTTP oferece outros métodos para escrever aos recursos, portanto, utilize-os adequadamente. Neste ponto, é importante lembrar as permissões e questões de segurança da API, o que nos leva ao nosso próximo tópico:

Usar criptografia SSL

Sua API RESTful deve necessariamente usar criptografia SSL.

Como sua web API pode ser acessada de qualquer lugar com acesso à Internet, como uma praça de compras, uma livraria, um café ou um aeroporto, sua preocupação é garantir o acesso seguro aos dados e serviços que sua API oferece.

No entanto, nem todos esses locais oferecem acesso seguro e criptografado.

Ter as informações que você está carregando codificadas é essencial. Além disso, o uso de SSL com tokens facilita a autenticação entre solicitações, impedindo que cada solicitação seja re-autenticada.

Crie versões para sua API

Como todos os software, as APIs devem crescer e evoluir. Não importa quão cuidadoso e experiente você seja, seu API não será perfeito na primeira versão.

E não tem que ser!

Muitas vezes, é melhor expor a primeira versão de seu API e desenvolvê-la gradualmente. Entretanto, tenha cuidado para não mudar muito seu design e acabar quebrando as aplicações que utilizavam as versões anteriores(como Jeremiah Lee, da Fitbit, disse na entrevista a Kleber, nosso CEO).

Portanto, ao criar uma nova versão para sua API, certifique-se de que a versão anterior ainda esteja disponível, não quebrando assim a funcionalidade do sistema. Após comunicar as mudanças aos desenvolvedores, e dando-lhes tempo para se adaptarem, as versões antigas podem ser descontinuadas, ou você pode mantê-las no ar, sem oferecer suporte.

Garanta o sucesso de seu API RESTful!

Os 7 passos detalhados acima garantirão que o onboarding (desenvolvedores começando a usar sua API) de sua API seja muito mais fácil!

Uma última dica é que você mantenha um olho na usabilidade de seu API. Verifique o artigo Como medir a usabilidade de um API.