Design de API REST: 7 dicas essenciais

Confira o Webinar API Design Restful

O Design de API REST em sua melhor versão

*atualizado em: 31 de março de 2020

Fazer o Design de API REST nada mais é do que criar uma interface com regras bem definidas, disponibilizada para que seja possível realizar a interação com um sistema e obter suas informações ou realizar operações.

É como eu expliquei lá nos artigos de O Que são APIs: sua interface deve funcionar como um garçom em um restaurante: recebendo seus pedidos e retornando recursos (ou pratos), sem que os clientes precisem visitar a cozinha para ir pegar o prato lá.

As APIs RESTful ganharam uma enorme aceitação em todo o mundo, principalmente por seguir um padrão moderno e bem definido. Porém, o design de uma API RESTful pode sofrer desvios de padronização, o que de fato acontece, muitas vezes por falta de um conhecimento sólido dos conceitos.

Neste post, vamos conhecer algumas dicas que permitem criar um design aprimorado e padronizado daquilo que chamamos de uma verdadeira API no padrão RESTful.

E é claro, é sempre bom considerar que, ao fazer o Design da sua API REST, você também precisa ter em mente quem irá utilizá-la, como será utilizada dentro da sua estratégia, e também como será exposta ao mundo. Esse raciocínio, colocando a API em lugar privilegiado no seu planejamento, se chama API First.

Felizmente, temos conteúdos que pode te ajudar em todas essas etapas!

Utilize 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
/createNewCustomer
/deleteCustomer

Estas são formas incorretas de nomenclatura, que se assemelham a funções de alguma linguagem de programação orientada a objetos. Ao invés disso, para o Design mais adequado, utilize substantivos, como:

/customers
/customers/563

Use corretamente os métodos HTTP

O princípio fundamental do REST consiste em separar sua API em recursos lógicos. Esses recursos são manipulados utilizando requisições HTTP com os métodos GET, POST, PUT e DELETE.

Por exemplo, ao realizar uma requisição ao recurso /customers/563 utilizando o método GET, você estará solicitando que seja recuperado um cliente específico com o código 563.

Da mesma forma, ao realizar a mesma requisição (ou seja, no endpoint /customers/536), utilizando o método DELETE, você estará realizando uma exclusão de um cliente específico, de código 563.

Utilize nomes no plural

O nome do endpoint deve estar no singular ou no plural?

Esta é uma pergunta que costuma gerar muita discussão no Design de APIs RESTful.

De modo geral, cabe a você escolher. Particularmente, prefiro os nomes no plural, já que indicam um conjunto de recursos (como no caso dos clientes, acima).

Porém, uma coisa é certa: não faça mistura de endpoints no singular e no plural. A recomendação é que você simplifique e utilize todos os nomes no plural.

Utilize sub-recursos para os relacionamentos

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

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

Quando for o caso, utilize sub-recursos nos endpoints.

Por exemplo, a requisição

GET /customers/231/projects/

deve retornar a lista de projetos do cliente 231. Já a requisição

GET /customers/231/projects/4

deve retorna o projeto #4 do cliente 231.

Não altere estados com o método GET

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

O método GET, como é intuitivo pelo nome, deve retornar apenas uma versão de leitura do recurso.

O HTTP oferece outros métodos para realizar escrita nos recursos, então use-os adequadamente. Nesse ponto, é importante lembrar das permissões e questões de Segurança de APIs, que já falamos nesse Webinar, o que nos leva ao nosso próximo tópico:

Utilize criptografia SSL

Sua API RESTful deve necessariamente utilizar criptografia SSL.

Como a sua API web pode ser acessada de qualquer lugar onde haja acesso à Internet, como uma praça de alimentação de um shopping center, uma livraria, um café ou um aeroporto, a preocupação em garantir um acesso seguro aos dados e serviços que sua API oferecem é sua.

Porém, nem todos esses locais conferem acesso seguro e criptografado.

Ter as informações que trafegam criptografadas é algo essencial. Além disso, utilizar SSL com tokens facilita a autenticação entre requisições, evitando-se que a cada requisição seja realizada nova autenticação.

Novamente, uma boa referência para estudar esse assunto é o Webinar de Segurança de APIs.

Crie versões para sua API

Como todo software, APIs devem crescer e evoluir. Por mais cuidadoso e experiente que você seja, sua API não será perfeita na primeira versão.

E nem precisa! Muitas vezes, é melhor expor a primeira versão da sua API e ir evoluindo-a aos poucos. Porém, tome cuidado em não alterar muito o seu design e acabar quebrando as aplicações que usavam as versões anteriores (como o Jeremiah Lee, do Fitbit, disse na entrevista para o Kleber, nosso CEO).

Portanto, ao criar uma nova versão para a sua API, garanta que a versão anterior ainda esteja disponível, não quebrando assim as funcionalidades de sistemas. Depois de comunicar as mudanças aos desenvolvedores, e dar um tempo de adaptação, versões antigas podem ser descontinuadas, ou você pode mantê-las no ar, sem oferecer suporte.

Garanta o sucesso da sua API RESTful!

Os 7 passos acima garantirão que o onboarding (começo do uso da sua API, por parte dos desenvolvedores) da sua API seja bem mais fácil!

Uma dica final é você ficar de olho na usabilidade da sua API, confira Como medir a usabilidade de uma API.