HTTP e APIs REST

O Spring MVC mapeia interações HTTP para métodos Java, mas as anotações não definem sozinhas uma boa API. Comece pela semântica HTTP e por um contrato de recurso.

Propriedades dos métodos

Método	Significado típico	Seguro	Idempotente
GET	Recuperar uma representação	Sim	Sim
POST	Processar ou criar sob um recurso	Não	Sem garantia
PUT	Substituir o estado no URI de destino	Não	Sim
PATCH	Aplicar uma modificação parcial	Não	Sem garantia
DELETE	Remover o estado de destino	Não	Sim

Idempotente significa que repetir a mesma requisição pretendida produz o mesmo efeito pretendido; as respostas podem diferir porque o estado, os timestamps ou os logs mudaram. Para operações inseguras que os clientes possam repetir após uma falha ambígua, defina um protocolo de chave de idempotência e deduplicação.

Um controller de recurso

@RestController
@RequestMapping("/books")
final class BookController {
    private final BookService books;

    BookController(BookService books) {
        this.books = books;
    }

    @GetMapping("/{id}")
    BookResponse find(@PathVariable UUID id) {
        return BookResponse.from(books.require(id));
    }

    @PostMapping
    ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest request) {
        Book created = books.create(request.toCommand());
        URI location = URI.create("/books/" + created.id());
        return ResponseEntity.created(location).body(BookResponse.from(created));
    }
}

DTOs de transporte impedem que preocupações da representação HTTP vazem para as entidades de persistência. Decida paginação, filtragem, ordenação, media types e regras de compatibilidade como parte do contrato público.

Status e cache

Use os códigos de status de acordo com sua semântica: 201 com Location para criação; 204 para uma resposta bem-sucedida e intencionalmente sem conteúdo; 400 para entrada malformada; 401 para autenticação ausente ou inválida; 403 para autorização insuficiente; 404 para um destino indisponível; e 409 para um conflito de estado aplicável.

Requisições condicionais com validadores como ETags podem evitar atualizações perdidas e a retransmissão de representações inalteradas. O comportamento de cache pertence aos cabeçalhos HTTP, não apenas a um cache da aplicação. A semântica do cache HTTP e o cache de métodos ou dados no servidor são contratos relacionados, mas distintos.

Exercícios

1. Projete uma estratégia idempotente de novas tentativas para a criação de recursos.
2. Explique a diferença entre PUT e PATCH.
3. Especifique os compromissos da paginação por cursor e por offset.

Consulte a especificação HTTP Semantics.