1. REST não é um framework, é um conjunto de convenções
REST (Representational State Transfer) é um estilo de arquitetura — um conjunto de convenções sobre como modelar operações como URLs + verbos HTTP, não uma biblioteca ou tecnologia específica. Você já consumiu APIs REST em Node/Express; os mesmos princípios se aplicam aqui, só muda a linguagem que os implementa.
2. Recursos, não ações, nas URLs
A ideia central: a URL identifica um recurso (um substantivo — clientes, pedidos), e o verbo HTTP diz o que fazer com ele. Ações não deveriam aparecer na URL.
| Evite (ação na URL) | Prefira (recurso + verbo) |
|---|---|
GET /obterCliente?id=42 | GET /clientes/42 |
POST /criarCliente | POST /clientes |
POST /excluirCliente/42 | DELETE /clientes/42 |
POST /listarClientesAtivos | GET /clientes?ativo=true |
3. Os verbos HTTP e seu significado
| Verbo | Papel | Idempotente? | Equivalente no Módulo 2 |
|---|---|---|---|
GET | Ler um recurso, sem efeitos colaterais | Sim | usp_ClienteObter / usp_ClienteListar |
POST | Criar um novo recurso | Não | usp_ClienteInserir |
PUT | Substituir um recurso inteiro | Sim | usp_ClienteAtualizar (substituindo todos os campos) |
PATCH | Atualizar parcialmente um recurso | Não necessariamente | Uma variação de update que só altera campos enviados |
DELETE | Remover um recurso | Sim | usp_ClienteExcluir |
Uma operação é idempotente se chamá-la uma vez ou várias vezes seguidas produz o mesmo
resultado final. DELETE /clientes/42 chamado duas vezes ainda deixa
o cliente 42 excluído (a segunda chamada só devolve 404). Já POST /clientes
chamado duas vezes cria dois clientes — por isso não é idempotente.
4. Códigos de status HTTP com propósito
| Código | Significado | Quando usar |
|---|---|---|
200 OK | Sucesso genérico | GET, PUT, PATCH bem-sucedidos |
201 Created | Recurso criado | POST bem-sucedido — inclui o header Location apontando para o novo recurso |
204 No Content | Sucesso, sem corpo de resposta | DELETE bem-sucedido |
400 Bad Request | A requisição está malformada/inválida | Falha de validação (Data Annotations, Módulo 3 capítulo 5) |
401 Unauthorized | Não autenticado | Faltou (ou expirou) o token de autenticação |
403 Forbidden | Autenticado, mas sem permissão | Usuário autenticado tentando uma ação que não pode fazer |
404 Not Found | Recurso não existe | GET /clientes/999 quando 999 não existe |
409 Conflict | Conflito com o estado atual | E-mail já cadastrado, estoque insuficiente (o erro 50010 do Módulo 2!) |
500 Internal Server Error | Erro não tratado do lado do servidor | Qualquer exceção que escapou sem tratamento — nunca deveria ser o "normal" |
O erro THROW 50010 (estoque insuficiente) da procedure
usp_PedidoCheckout deveria virar um 409 Conflict
na API — não um 500. O código 500 deveria significar "algo quebrou de
forma inesperada", nunca "uma regra de negócio esperada impediu a operação".
5. Stateless — cada requisição se basta
REST assume que o servidor não guarda "memória de conversa" entre requisições — cada uma chega com toda a informação necessária (incluindo autenticação, no cabeçalho) para ser processada independentemente. Isso é o que permite escalar uma API horizontalmente (várias instâncias idênticas atrás de um load balancer) sem se preocupar em qual instância atendeu a requisição anterior.
6. Onde isso te leva
Com os princípios estabelecidos, o próximo capítulo coloca a mão na massa: como o ASP.NET Core implementa esses conceitos, tanto no formato clássico (Controllers) quanto no mais recente e minimalista (Minimal APIs).