INTENÇÃO E RESULTADO
O endpoint é uma frase: método + recurso → status.
O caminho identifica o recurso; o método diz qual semântica a requisição pretende. O servidor executa a operação permitida e escolhe um status que comunique o resultado. O conteúdo pode detalhar, mas não deveria contradizer esse status.
Laboratório visual · Quatro histórias HTTP
Compare leitura, criação, substituição e recurso ausente.
GET: obtém uma representação sem pedir alteração do recurso.
MÉTODOS MAIS ENCONTRADOS
Escolha pela semântica, não pela conveniência do framework.
| Método | Intenção | Seguro? | Idempotente? | Exemplo |
|---|---|---|---|---|
| GET | Obter a representação atual do recurso. | Sim | Sim | GET /produtos/42 |
| HEAD | Obter os campos de um GET equivalente sem conteúdo. | Sim | Sim | Testar metadados e cache. |
| POST | Submeter conteúdo para processamento conforme o recurso. | Não | Não | POST /pedidos |
| PUT | Criar ou substituir o estado do recurso no URI conhecido. | Não | Sim | PUT /perfis/7 |
| PATCH | Aplicar modificações parciais descritas pelo conteúdo. | Não | Não por definição | PATCH /perfis/7 |
| DELETE | Remover a associação do recurso com seu URI. | Não | Sim | DELETE /itens/9 |
| OPTIONS | Descobrir opções de comunicação para o alvo. | Sim | Sim | Também participa do preflight CORS. |
Seguro significa que o cliente não pediu alteração de estado; métricas e logs podem acontecer como efeito colateral. Idempotente orienta retries e intermediários, mas não elimina a necessidade de controlar concorrência e efeitos externos.
STATUS CODES
A classe dá a direção; o código específico explica o desfecho.
| Código | Use quando | Não confunda |
|---|---|---|
| 200 OK | Operação concluída e há uma representação útil. | Não usar 200 com {"erro":true} para toda falha. |
| 201 Created | Um ou mais recursos foram criados. | Use Location quando puder apontar o principal recurso. |
| 204 No Content | Sucesso sem conteúdo de resposta. | Não enviar JSON ou espaço no body. |
| 304 Not Modified | A representação armazenada continua válida após requisição condicional. | Não é “redirecionar para outra URL”. |
| 400 Bad Request | O servidor não consegue processar o pedido por problema do cliente. | Forneça detalhes seguros e acionáveis. |
| 401 Unauthorized | Faltam credenciais válidas para o recurso. | Na prática significa “não autenticado”; pode usar WWW-Authenticate. |
| 403 Forbidden | O servidor entendeu, mas recusa autorizar. | Não revelar informação sensível na justificativa. |
| 404 Not Found | Não há representação atual ou o servidor não quer revelar sua existência. | Não implica erro de sintaxe da URL. |
| 409 Conflict | O pedido conflita com o estado atual do recurso. | Útil para conflito de versão ou unicidade conhecido. |
| 429 Too Many Requests | O cliente excedeu uma política de taxa. | Pode orientar espera com Retry-After. |
| 500 / 503 | Falha inesperada / indisponibilidade temporária. | 503 pode usar Retry-After; retry precisa de limite e jitter. |
HEADERS SÃO CAMPOS DE CONTEXTO
Alguns descrevem a representação; outros controlam a troca.
Representação
Content-Type, Content-Length, Content-Encoding e Content-Language descrevem os bytes transferidos.
Negociação
Accept, Accept-Encoding e Accept-Language expressam preferências do cliente.
Cache
Cache-Control, ETag, Last-Modified, If-None-Match e Vary coordenam reuso.
Autenticação
Authorization, WWW-Authenticate, Cookie e Set-Cookie participam de credenciais e estado.
Navegação
Location, Referer e políticas de redirecionamento ajudam a entender o caminho da interação.
Políticas
CSP, HSTS, CORS e outros campos influenciam como navegadores permitem conteúdo, canal e acesso entre origens.
Set-Cookie, por exemplo, não deve ser combinado como uma lista comum.ADICIONANDO CONTEXTO ENTRE REQUISIÇÕES
Cookie fica no agente do usuário; sessão costuma guardar estado no servidor.
O servidor envia Set-Cookie. O navegador armazena nome, valor e atributos e, em requisições futuras, calcula quais cookies são aplicáveis. Uma sessão tradicional guarda apenas um identificador opaco no cookie e associa esse ID a dados mantidos no servidor.
Laboratório visual · Ciclo de uma sessão
Avance do login até a invalidação.
Antes do login: o navegador ainda não possui um identificador de sessão aplicável ao site.
Set-Cookie: __Host-sid=a8f2…; Path=/; Secure; HttpOnly; SameSite=Lax| Elemento | Função | Limite importante |
|---|---|---|
| Secure | Restringe o envio a conexões seguras. | Não torna o valor criptografado dentro do navegador. |
| HttpOnly | Impede acesso pelo document.cookie. | Ajuda contra roubo via XSS, mas não impede requisições feitas pelo script malicioso. |
| SameSite | Restringe envio em contextos cross-site segundo a política. | É defesa importante contra CSRF, não substitui todas as medidas. |
| Path e Domain | Definem escopo de envio. | Path não é barreira de confidencialidade entre páginas da mesma origem. |
| Max-Age / Expires | Controlam persistência do cookie. | A sessão no servidor também deve expirar e poder ser revogada. |
NÃO CONFUNDA RECIPIENTE COM MODELO
Cookie, sessão e token respondem a perguntas diferentes.
| Conceito | Onde fica | Como viaja | Cuidado |
|---|---|---|---|
| Cookie | Cookie store do navegador. | O navegador anexa automaticamente quando aplicável. | CSRF, escopo, atributos, tamanho e privacidade. |
| Sessão server-side | Memória, cache ou banco do servidor. | Um ID costuma viajar em cookie. | Expiração, revogação, fixação e compartilhamento entre réplicas. |
| Token bearer | Depende do cliente e da arquitetura. | Frequentemente em Authorization: Bearer. | Quem possui o token pode usá-lo; armazenamento e logs são críticos. |
| localStorage | Armazenamento por origem acessível a JavaScript. | Não é enviado automaticamente; o script precisa lê-lo. | Um XSS pode ler os dados; não é substituto automático de cookie seguro. |
PARE E PENSE
Se HttpOnly impede JavaScript de ler o cookie de sessão, então XSS deixou de ser perigoso?
CONTINUE EXPLORANDO
Referências e itens adicionais de estudo
Referências técnicas
Registros e padrões atuais.
- RFC 9110 · HTTP Semantics — métodos, status e campos.
- IANA · HTTP Method Registry — propriedades oficiais dos métodos.
- IANA · HTTP Status Code Registry — códigos registrados.
- IANA · HTTP Field Name Registry — campos permanentes e provisórios.
- RFC 10025 · Cookies — padrão atual, publicado em 2026 e substituto da RFC 6265.
- RFC 5789 · PATCH Method — modificações parciais.
Itens adicionais de estudo
Prática guiada.
- Modele CRUD sem assumir uma correspondência mecânica: justifique método, recurso e status de cada operação.
- No DevTools, localize
Set-Cookie, o cookie armazenado e seu envio posterior. - Compare uma resposta 200 baixada, 304 revalidada e servida diretamente do cache.
- Estude CSRF e XSS e relacione cada defesa ao ataque correto.
- Projete logout em todos os dispositivos e rotação de ID após autenticação.