O paradigma REST

A transferência de Estado Representacional (REST) é a escolha mais popular para o desenvolvimento da API nos últimos anos.

Baseado no conceito central de recursos. Um recurso é uma entidade que pode ser identificada, nomeada, endereçada ou tratada na web.

As APIs REST expõem dados como recursos e usam métodos HTTP padrão para representar transações Criar, Ler, Atualizar e Excluir (CRUD) contra esses recursos.
Por exemplo, a API da Stripe representa clientes, encargos, saldos, reembolsos, eventos, arquivos e pagamentos como recursos.

Exemplo na API do Sripe

Requisição HTTP para recuperar uma cobrança da API Stripe

**GET**
/v1/charges/ch_CWyut1Xs9pZyfD
HOST api.stripe.com
Authorization: Bearer YNoJlYq64iCBhzfL9HNO00fzVrsEjtV

Requisição HTTP para enviar uma cobrança na API Stripe

POST 
/v1/charges
HOST api.stripe.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bea
rer
YNoJlYq64iCBhzfL9HNO00fzVrsEjtVl

amount=2000&currency=usd

Uso de métodos HTTP

• Métodos HTTP como GET, POST, UPDATE e DELETE informam o servidor sobre a ação a ser realizada.
• Diferentes métodos HTTP invocados na mesma URL fornecem funcionalidades diferentes.
• Criar: Use o POST, na maioria dos casos, para criar novos recursos.
• Ler: Use o GET para ler recursos. Requisições GET nunca mudam o estado do recurso. Elas não têm efeitos colaterais. O GET é idempotente.
• Atualização: Use o PUT para substituir um recurso e PATCH para atualizações parciais para os recursos existentes. o PUT também é idempotente
• Excluir: Use o DELETE para excluir recursos existentes. O DELETE também é idempotente

Nomenclatura

Os recursos fazem parte de URLs, como /usuarios

Para cada recurso, duas URLs são geralmente implementadas: uma para a coleção, como /usuarios, e uma para elemento específico, como /usuarios/U123

Nomes são usados em vez de verbos para definir recursos. Por exemplo, em vez de /lerInformacaoUsuario/U123, use /usuario/U123.

Códigos de Resposta

Imagine que você envia uma carta para alguém. A resposta que você recebe de volta pode ser:

• ✅ "Entregue com sucesso!"
• 🔄 "O destinatário se mudou, tente outro endereço"
• ❌ "Carta com endereço errado"
• 💥 "O correio teve um problema interno"

É exatamente assim que funcionam os códigos HTTP — são respostas do servidor ao seu navegador/aplicação.

Geralmente, os códigos na faixa 2XX indicam sucesso, 3XX indicam que um recurso de moveu e códigos na faixa 4XX indicam um erro do lado do cliente (como um parâmetro necessário ausente ou muitas solicitações).

Códigos na faixa 5XX indicam erros do lado do servidor.

Descomplicando Tabela de Códigos

🟢 2XX — Sucesso

O servidor recebeu, entendeu e processou sua requisição.

🔵 3XX — Redirecionamento

O recurso que você pediu está em outro lugar.

🟡 4XX — Erro do Cliente

Você fez algo errado na requisição.

🔴 5XX — Erro do Servidor

O servidor que teve um problema, não você.

Formatos de resposta

As APIs REST podem devolver respostas JSON ou XML. E devido à sua simplicidade e facilidade de uso com Javascript, o JSON tornou-se o padrão para APIs modernas.

O XML e outros formatos ainda podem ser suportados para facilitar a adoção para clientes que ainda estão trabalhando nesse formatos usando APIs semelhantes.

No Brasil, o XML é comum em APIs do governo para facilitar a governança dos dados, como NF-E ou E-Social

Convenções para um CRUD com REST

Operações não CRUD

Além das operações típicas da CRUD que acabamos de olhar, as APIs REST às vezes precisam representar operações não-CRUD.

As seguintes abordagens são comumente usadas nesse caso:

1. Crie uma ação como um subrecurso.

GET livros/empromocao

1. Crie uma ação através de parâmetros de entrada

GET livros?tipo=empromocao&categoria=autoajuda