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¤cy=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.
| Código | Nome | Significado |
|---|---|---|
| 200 | OK | Tudo certo! Resposta padrão de sucesso |
| 201 | Created | Um recurso foi criado (ex: cadastro feito) |
| 204 | No Content | Sucesso, mas sem nada para retornar |
🔵 3XX — Redirecionamento
O recurso que você pediu está em outro lugar.
| Código | Nome | Significado |
|---|---|---|
| 301 | Moved Permanently | Mudou de endereço para sempre |
| 302 | Found | Redirecionamento temporário |
| 304 | Not Modified | Use o cache, nada mudou |
🟡 4XX — Erro do Cliente
Você fez algo errado na requisição.
| Código | Nome | Significado |
|---|---|---|
| 400 | Bad Request | Requisição mal formada |
| 401 | Unauthorized | Precisa estar autenticado (fazer login) |
| 403 | Forbidden | Autenticado, mas sem permissão |
| 404 | Not Found | O recurso não existe |
| 429 | Too Many Requests | Você fez requisições demais (rate limit) |
🔴 5XX — Erro do Servidor
O servidor que teve um problema, não você.
| Código | Nome | Significado |
|---|---|---|
| 500 | Internal Server Error | Erro genérico no servidor |
| 502 | Bad Gateway | Servidor intermediário recebeu resposta inválida |
| 503 | Service Unavailable | Servidor fora do ar ou sobrecarregado |
| 504 | Gateway Timeout | O servidor demorou demais para responder |
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ção | Verbo HTTP | URL: /usuarios | URL: /usuários/123 |
|---|---|---|---|
| Criar | POST | Cria um novo usuário | Não é aplicável |
| Ler | GET | Lista todos os usuários | Recupera o usuário 123 |
| Atualizar | PUT ou PATCH | Atualiza em lote os usuários | Atualiza o usuário 123 |
| Remover | DELETE | Apaga todos os usuários | Apaga o usuário 123 |
| Verbo HTTP | URI Exemplo | Semântica |
|---|---|---|
| POST | /livros/123/autores | Criar os autores para o livro 123 |
| GET | /livros/123/autores/1 | Recupera o autor 1 do livro 123 |
| PUT ou PATCH | /livros/123/autores/1 | Atualiza os dados do autor 1 do livro 123 |
| DELETE | /livros/123/autores | Apaga todos os autores do livro 123 |
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:
- Crie uma ação como um subrecurso.
GET livros/empromocao
- Crie uma ação através de parâmetros de entrada
GET livros?tipo=empromocao&categoria=autoajuda
Top comments (0)