Skip to content

HTTP Folha de referência

HyperText Transfer Protocol para comunicação cliente-servidor.

01

Primeiros passos

Requisição e resposta HTTP

HTTP é um protocolo requisição-resposta. Clientes enviam requisições (função, path, headers, corpo opcional), servidores respondem com status, headers e corpo. HTTP/1.1 é baseado em texto, HTTP/2 e HTTP/3 usam framing binário.

http
# HTTP Request
GET /api/users HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0
Accept: application/json

# HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 45

{"id": 1, "name": "Alice", "email": "[email protected]"}

Estrutura de URL

URLs identificam recursos. O scheme seleciona o protocolo. O host é resolvido via DNS. A porta padrão é implícita quando omitida. O fragmento (#) é apenas do cliente e removido antes de enviar ao servidor. Query strings são comumente usadas para filtragem/paginação.

http
# Generic URL format
scheme://userinfo@host:port/path?query#fragment

# Example
https://user:[email protected]:8443/api/v1/users?page=2#section

# Components
# scheme    - https (protocol)
# userinfo  - user:pass (rare, deprecated)
# host      - example.com (domain or IP)
# port      - 8443 (default: 80 for http, 443 for https)
# path      - /api/v1/users (resource location)
# query     - page=2 (key=value pairs, & separated)
# fragment  - section (client-only, never sent to server)

Panorama das versões HTTP

HTTP/0.9 era um protótipo minimalista. HTTP/1.0 adicionou headers e content types, mas abria uma nova conexão por requisição. HTTP/1.1 introduziu conexões persistentes, o header Host obrigatório (habilitando virtual hosts) e pipelining. HTTP/2 adicionou multiplexação binária. HTTP/3 roda sobre QUIC, eliminando o bloqueio head-of-line na camada de transporte.

http
# HTTP/0.9 (1991) - single GET, no headers
GET /page.html

# HTTP/1.0 (1996) - headers, status codes, multiple types
GET /page.html HTTP/1.0

# HTTP/1.1 (1997) - persistent connections, Host header, pipelining
GET /page.html HTTP/1.1
Host: example.com

# HTTP/2 (2015) - binary, multiplexing, header compression
# (negotiated via ALPN or h2c upgrade)

# HTTP/3 (2022) - over QUIC (UDP-based)
# (negotiated via Alt-Svc header)

Ciclo de vida da conexão

HTTP/1.1 mantém as conexões TCP abertas por padrão (keep-alive), evitando o custo de handshakes repetidos. Múltiplas requisições podem ser enviadas numa única conexão. O header Connection: close sinaliza a última requisição. HTTP/2 multiplexa muitos streams sobre uma única conexão. Timeout e max do Keep-Alive são configuráveis no servidor.

http
# HTTP/1.1 persistent connection (keep-alive)
GET /page1 HTTP/1.1
Host: example.com
Connection: keep-alive

# (server responds, connection stays open)
HTTP/1.1 200 OK
Content-Length: 128
Connection: keep-alive

# Client reuses same TCP connection for next request
GET /page2 HTTP/1.1
Host: example.com

# Closing the connection
GET /final HTTP/1.1
Host: example.com
Connection: close

Formato da mensagem

Mensagens HTTP começam com uma start-line (request-line ou status-line), seguida de headers, uma linha em branco e um corpo opcional. As linhas usam finais CRLF. Nomes de headers não diferenciam maiúsculas. A linha em branco é obrigatória e sinaliza o início do corpo. Corpos podem ter qualquer comprimento (chunked) ou fixo (Content-Length).

http
# Request format
<METHOD> <PATH> <VERSION>

<Header-Name>: <value>

...



<optional body>

# Response format
<VERSION> <STATUS> <REASON>

<Header-Name>: <value>

...



<optional body>

# Lines end with CRLF (
). Headers are case-insensitive.
# A blank line (
) separates headers from body.

Depuração com telnet / HTTP bruto

Você pode falar HTTP bruto sobre TCP usando nc ou telnet (porta 80) ou openssl s_client (HTTPS). Isso é valioso para depurar. Você precisa incluir o header Host em HTTP/1.1+. Duas linhas em branco terminam a requisição. curl -v mostra a conversa em formato de fio, incluindo headers.

http
# Manual HTTP request via netcat/nc
nc example.com 80
GET / HTTP/1.1
Host: example.com

# (press Enter twice to send blank line)

# Using openssl for HTTPS
openssl s_client -connect example.com:443
GET / HTTP/1.1
Host: example.com

# curl with --http1.1 to force version
curl -v --http1.1 https://example.com
curl -v --http2 https://example.com
curl -v --http3 https://example.com
02

Verbos HTTP

GET — buscar recurso

GET recupera uma representação de um recurso. Deve ser seguro (sem efeitos colaterais) e idempotente (repetível). Requisições GET são cacheáveis e favoritáveis. Embora a spec permita um corpo, isso é desencorajado — proxies e CDNs podem removê-lo. Use query parameters para filtrar em vez disso.

http
# Basic GET
GET /api/users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

# GET with query parameters
GET /api/users?role=admin&active=true HTTP/1.1
Host: api.example.com

# GET should be safe & idempotent
# - safe: no server state change
# - idempotent: repeating yields same result
# - cacheable: yes
# - body allowed but discouraged (some clients/servers reject)

POST — criar recurso

POST envia dados para serem processados. É usado para criar novos recursos em que o servidor atribui a URI (por exemplo, /api/users → /api/users/43). POST não é nem seguro nem idempotente — enviar duas vezes pode criar dois recursos. A resposta 201 Created deve incluir um header Location apontando para o novo recurso.

http
# POST creating a new resource
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 52

{"name": "Bob", "email": "[email protected]", "age": 30}

# Response typically 201 Created with Location header
HTTP/1.1 201 Created
Location: /api/users/43
Content-Type: application/json

{"id": 43, "name": "Bob"}

# POST is neither safe nor idempotent.
# Repeating may create duplicate resources.

PUT — substituir recurso

PUT substitui o recurso inteiro na URI alvo pelo corpo da requisição. É idempotente — repetir o mesmo PUT produz o mesmo estado final. PUT mira uma URI específica (por exemplo, /users/43), diferente de POST que mira uma coleção. Se um campo for omitido no PUT, ele normalmente é removido (substituição completa).

http
# PUT replaces the entire resource at the given URI
PUT /api/users/43 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 60

{"id": 43, "name": "Robert", "email": "[email protected]", "age": 31}

# Idempotent: sending the same PUT again yields the same state.
# If the resource doesn't exist, PUT may create it (server-dependent).

# Response
HTTP/1.1 200 OK
# or 204 No Content if no body returned

PATCH — atualização parcial

PATCH aplica atualizações parciais a um recurso, diferente de PUT que o substitui inteiramente. A forma mais simples é JSON Merge Patch (RFC 7396): envie apenas os campos a mudar. JSON Patch (RFC 6902) usa um array de operações (add, remove, replace, move, copy, test). PATCH NÃO é idempotente por padrão, embora merge-patch seja.

http
# PATCH applies partial modifications
PATCH /api/users/43 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json
Content-Length: 22

{"email": "[email protected]"}

# Only the email field is updated; other fields remain.

# JSON Patch (RFC 6902) - structured operations
PATCH /api/users/43 HTTP/1.1
Content-Type: application/json-patch+json

[
  {"op": "replace", "path": "/email", "value": "[email protected]"},
  {"op": "remove", "path": "/age"}
]

DELETE — remover recurso

DELETE remove o recurso alvo. É idempotente — excluir o mesmo recurso duas vezes deve deixar o servidor no mesmo estado. Códigos de sucesso comuns são 204 (sem corpo), 200 (com corpo confirmando) ou 202 (exclusão assíncrona). A maioria das APIs exige autenticação. Se retornar 404 num recurso ausente é debatido — 204 é mais seguro para idempotência.

http
# Delete a resource
DELETE /api/users/43 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

# Successful responses:
HTTP/1.1 204 No Content        # most common
HTTP/1.1 200 OK                 # if body returned
HTTP/1.1 202 Accepted           # async deletion queued

# Idempotent: deleting an already-deleted resource
# should still return 204 (or 404 — debatable).

HEAD e OPTIONS

HEAD é idêntico a GET, mas o servidor retorna só headers (sem corpo) — útil para verificar Content-Length, Content-Type ou Last-Modified sem baixar o corpo. OPTIONS pergunta quais verbos são permitidos (header Allow) e é usado pelos navegadores para preflight de CORS. Ambos são seguros e idempotentes.

http
# HEAD: like GET but returns headers only (no body)
HEAD /api/users/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 128
# (no body)

# OPTIONS: describe communication options
OPTIONS /api/users HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Allow: GET, POST, HEAD, OPTIONS
Access-Control-Allow-Methods: GET, POST
03

Códigos de status

1xx Informativos

Códigos 1xx são informativos, indicando que a requisição foi recebida e o processamento continua. 100 Continue permite que um cliente verifique se deve enviar um corpo grande (pareado com o header Expect: 100-continue). 101 Switching Protocols habilita WebSocket. 103 Early Hints permite que o servidor dê dicas ao navegador de pré-carregar assets antes de a resposta final estar pronta.

http
# 100 Continue - server received headers, client may send body
POST /upload HTTP/1.1
Host: example.com
Expect: 100-continue
Content-Length: 1048576

# Server replies:
HTTP/1.1 100 Continue
# (client now sends the request body)

# 101 Switching Protocols - used for WebSocket upgrade
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

# 103 Early Hints - preload resources before final response
HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style

2xx Sucesso

Códigos 2xx indicam sucesso. 200 OK é o sucesso genérico. 201 Created indica que um novo recurso foi criado (com um header Location). 202 Accepted significa que a requisição está na fila para processamento assíncrono (por exemplo, um job longo). 204 No Content sinaliza sucesso sem corpo — comum para DELETE/PUT. 206 Partial Content retorna parte de um recurso (requisição Range).

http
# 200 OK - standard success
HTTP/1.1 200 OK

# 201 Created - new resource created (POST/PUT)
HTTP/1.1 201 Created
Location: /api/users/43

# 202 Accepted - request queued for async processing
HTTP/1.1 202 Accepted

# 204 No Content - success, no body (DELETE, PUT)
HTTP/1.1 204 No Content

# 206 Partial Content - Range request result
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/2048

3xx Redirecionamentos

Códigos 3xx indicam redirecionamento. 301/308 são permanentes (cacheáveis, o valor de links de SEO passa); 302/307 são temporários. A diferença crucial: 301 e 302 historicamente permitiam conversão POST→GET (causando perda de dados), enquanto 307 e 308 preservam estritamente a função. 304 Not Modified é retornado em requisições condicionais quando o cache é válido — sem corpo enviado.

http
# 301 Moved Permanently - cacheable, change bookmarks
HTTP/1.1 301 Moved Permanently
Location: https://newsite.com/page

# 302 Found - temporary redirect (don't update bookmarks)
HTTP/1.1 302 Found
Location: /login

# 304 Not Modified - cache is still valid (conditional GET)
HTTP/1.1 304 Not Modified
ETag: "abc123"

# 307 Temporary Redirect - preserves method (POST stays POST)
HTTP/1.1 307 Temporary Redirect
Location: /new-endpoint

# 308 Permanent Redirect - permanent, preserves method
HTTP/1.1 308 Permanent Redirect
Location: https://newsite.com/api

4xx Erros de cliente

Códigos 4xx significam que o cliente errou. 400 Bad Request é entrada malformada. 401 significa autenticação ausente/inválida (deve incluir WWW-Authenticate). 403 significa autenticado, mas sem permissão. 404 é recurso ausente. 429 indica rate limiting (inclua Retry-After). Outros comuns: 405 Method Not Allowed, 409 Conflict, 422 Unprocessable Entity.

http
# 400 Bad Request - malformed syntax
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error": "Invalid JSON in request body"}

# 401 Unauthorized - authentication required
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

# 403 Forbidden - authenticated but not allowed
HTTP/1.1 403 Forbidden

# 404 Not Found - resource doesn't exist
HTTP/1.1 404 Not Found

# 429 Too Many Requests - rate limit hit
HTTP/1.1 429 Too Many Requests
Retry-After: 60

5xx Erros de servidor

Códigos 5xx significam que o servidor falhou. 500 é o catch-all para erros não tratados (verifique os logs do servidor). 501 significa que o servidor não implementa a função. 502 significa que um proxy/gateway recebeu uma resposta ruim do upstream. 503 significa sobrecarga temporária (use Retry-After). 504 significa timeout de upstream. Clientes podem tentar de novo 502/503/504 com backoff.

http
# 500 Internal Server Error - generic server failure
HTTP/1.1 500 Internal Server Error

# 501 Not Implemented - server doesn't support the method
HTTP/1.1 501 Not Implemented

# 502 Bad Gateway - upstream server returned invalid response
HTTP/1.1 502 Bad Gateway

# 503 Service Unavailable - temporary overload or maintenance
HTTP/1.1 503 Service Unavailable
Retry-After: 300

# 504 Gateway Timeout - upstream didn't respond in time
HTTP/1.1 504 Gateway Timeout

Padrões de código de status

Um mapeamento consistente de códigos de status torna as APIs previsíveis. Use 2xx para sucesso com precisão semântica (201 para criar, 204 para sem corpo). 4xx para erros de cliente com o código mais específico (409 para conflitos, 422 para validação). 401 vs 403 é a confusão mais comum: 401 = 'quem é você?', 403 = 'sei quem você é, mas não pode fazer isso'.

http
# REST API common mapping
GET     /users      -> 200
POST    /users      -> 201 (Created)
GET     /users/42   -> 200 | 404
PUT     /users/42   -> 200 | 201 (if created) | 404
PATCH   /users/42   -> 200 | 404
DELETE  /users/42   -> 204 | 404

# Validation errors
400 -> malformed JSON, missing required field
409 -> duplicate resource / version conflict
422 -> semantic validation failure (some APIs)

# Auth flow
401 -> no/invalid token (login required)
403 -> logged in but lacking permission
404 -> hide existence from unauthorized users

# Use 418 I'm a teapot for fun (RFC 2324 joke).
04

Headers de requisição

Headers de requisição comuns

Headers de requisição comuns transmitem identidade do cliente (User-Agent), formato de resposta desejado (família Accept), controle de conexão (Connection), autenticação (Authorization), estado (Cookie) e origem (Referer/Origin). Host é obrigatório em HTTP/1.1+ para virtual hosting. Content-Type e Content-Length descrevem qualquer corpo de requisição.

http
GET /api/data HTTP/1.1
Host: api.example.com          # target host (mandatory in HTTP/1.1)
User-Agent: Mozilla/5.0        # client identity
Accept: application/json        # desired response format
Accept-Language: en-US,en;q=0.9
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Authorization: Bearer <token>
Cookie: session=abc123; theme=dark
Referer: https://example.com/
Origin: https://example.com
Content-Type: application/json
Content-Length: 42

Headers Accept (content negotiation)

A família Accept dirige a content negotiation. Valores de qualidade (q, 0-1) expressam preferência — maior é mais preferido. */* é um curinga catch-all. O servidor escolhe a melhor correspondência do que suporta; se nenhuma casar, retorna 406 Not Acceptable (embora a maioria dos servidores caia num padrão em vez de 406). Brotli (br) e zstd oferecem melhor compressão que gzip.

http
# Accept: desired media types with quality (q) values
Accept: text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8

# Accept-Language: preferred languages
Accept-Language: en-US,en;q=0.9, zh-CN;q=0.8, fr;q=0.7

# Accept-Encoding: accepted compression algorithms
Accept-Encoding: gzip, deflate, br, zstd;q=0.9

# q=1.0 is default. Higher q = more preferred.
# */* matches any type.
# Server responds with 406 Not Acceptable if it can't satisfy.

Authorization e headers de auth

Authorization carrega credenciais. Basic auth envia username:password codificado em base64 a cada requisição (use sempre HTTPS). Bearer tokens são strings opacas (frequentemente JWTs) usados no OAuth 2.0. Esquemas de auth personalizados (X-API-Key) são comuns para API gateways. O base64 do Basic auth é encoding, não criptografia — não oferece segurança sem TLS.

http
# Basic Authentication (base64 of user:pass)
Authorization: Basic dXNlcjpwYXNz
# dXNlcjpwYXNz = base64("user:pass")

# Bearer Token (OAuth 2.0 / JWT)
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# API Key in header (custom)
X-API-Key: abc123def456

# Proxy authentication
Proxy-Authorization: Basic dXNlcjpwYXNz

# WARNING: Basic auth sends credentials on every request.
# Always use HTTPS to prevent eavesdropping.

User-Agent e Referer

User-Agent identifica o cliente, mas a maioria dos navegadores finge ser Mozilla/5.0 por compatibilidade retroativa (sniffing histórico). Referer (com erro de grafia na spec, nunca corrigido) diz ao servidor qual página linkou para a requisição — usado para analytics e proteção contra hotlink. Origin é scheme+host+porta, enviado por navegadores em requisições CORS e POSTs.

http
# User-Agent identifies the client software
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36

# Common browsers prepend "Mozilla/5.0" for historical compatibility
# (servers used to serve different content to different browsers)

# Referer: page that linked to this request
Referer: https://example.com/search?q=hello

# Origin: scheme + host + port (used by CORS)
Origin: https://example.com

# Note: "Referer" is the official spelling (misspelled in the original spec)

Headers de requisição condicional

Headers condicionais habilitam caching eficiente e controle de concorrência. If-None-Match (com ETag) e If-Modified-Since (com Last-Modified) tornam o GET condicional — o servidor retorna 304 se o cache é válido. If-Match e If-Unmodified-Singe protegem PUT/PATCH contra atualizações perdidas (concorrência otimista). If-Range habilita requisições de faixa atômicas.

http
# Conditional GET - only fetch if changed
If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT
If-None-Match: "abc123"

# If-Match / If-Unmodified-Since - for safe PUT/PATCH
If-Match: "abc123"
If-Unmodified-Since: Wed, 21 Oct 2023 07:28:00 GMT

# If-Range - for range requests (all-or-nothing)
If-Range: "abc123"
Range: bytes=0-1023

# Typical flow:
# 1. Server sends ETag/Last-Modified with response
# 2. Client sends If-None-Match/If-Modified-Since on next request
# 3. Server replies 304 if unchanged, 200 if changed

Headers personalizados e X-Headers

Headers personalizados historicamente usavam o prefixo X-, mas a RFC 6648 descontinuou essa convenção em 2012. Headers novos devem abandonar o X- (por exemplo, Request-ID, não X-Request-ID). X-Forwarded-For e X-Forwarded-Proto carregam informações do cliente através de proxies (nota: falsificáveis). A alternativa padronizada é Forwarded (RFC 7239). Traceparent/Tracestate habilitam tracing distribuído (W3C).

http
# X- prefixed headers (deprecated convention, but widely used)
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
X-Correlation-ID: abc-123
X-Forwarded-For: 203.0.113.1, 70.41.3.18
X-Forwarded-Proto: https
X-Real-IP: 203.0.113.1
X-RateLimit-Remaining: 42

# Modern recommendation: avoid X- prefix (RFC 6648)
# Use a namespace instead:
Request-ID: 550e8400-e29b-41d4-a716-446655440000
Traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

# Forwarded (RFC 7239) - standardized proxy info
Forwarded: for=203.0.113.1; proto=https; host=example.com
05

Headers de resposta

Headers de resposta comuns

Headers de resposta comuns descrevem o servidor (Server), o corpo da resposta (Content-Type, Content-Length), controle de conexão (Connection), caching (Cache-Control, ETag, Last-Modified), content negotiation (Vary), estado (Set-Cookie) e CORS (Access-Control-*). Date é obrigatório e usa o formato RFC 1123 em GMT.

http
HTTP/1.1 200 OK
Server: nginx/1.25.0
Date: Wed, 21 Oct 2023 07:28:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 128
Connection: keep-alive
Cache-Control: public, max-age=3600
ETag: "abc123"
Last-Modified: Mon, 20 Oct 2023 10:00:00 GMT
Vary: Accept-Encoding
Set-Cookie: session=xyz; HttpOnly; Secure
Access-Control-Allow-Origin: https://example.com

Headers de conteúdo

Headers Content-* descrevem o corpo. Content-Type é o MIME type e é crítico. Content-Length dá a contagem exata de bytes (obrigatório, exceto com encoding chunked). Content-Encoding indica compressão (gzip, br). Content-Disposition força download com um nome de arquivo. Content-Range acompanha respostas 206 Partial Content.

http
# Body metadata
Content-Type: application/json; charset=utf-8
Content-Length: 128                # exact byte count
Content-Encoding: gzip             # applied encoding
Content-Language: en-US
Content-Location: /api/users/42.json
Content-Disposition: attachment; filename="report.pdf"
Content-Range: bytes 0-1023/2048   # for partial content

# For chunked transfer (no Content-Length known upfront)
Transfer-Encoding: chunked

# MIME type format: type/subtype; parameter=value
# e.g., text/html; charset=UTF-8

Headers de segurança

Headers de segurança endurecem os navegadores contra ataques comuns. HSTS força HTTPS e previne SSL stripping. X-Content-Type-Options: nosniff impede MIME sniffing. X-Frame-Options (ou CSP frame-ancestors) bloqueia clickjacking. CSP é o mais poderoso — controla quais recursos podem carregar e executar. Referrer-Policy limita a informação de referer vazada. Defina-os em toda resposta.

http
# Force HTTPS for 6 months (incl. subdomains)
Strict-Transport-Security: max-age=15768000; includeSubDomains; preload

# Prevent MIME-type sniffing
X-Content-Type-Options: nosniff

# Prevent clickjacking
X-Frame-Options: DENY
# Or modern CSP frame-ancestors:
Content-Security-Policy: frame-ancestors 'none'

# Referrer policy
Referrer-Policy: strict-origin-when-cross-origin

# Permissions policy (feature lockdown)
Permissions-Policy: geolocation=(), camera=()

# Full Content-Security-Policy
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com

Headers de resposta CORS

Headers CORS (Cross-Origin Resource Sharing) permitem que um servidor opte por requisições cross-origin. Access-Control-Allow-Origin é obrigatório para qualquer leitura cross-origin; ou uma origem específica ou *. Se credenciais estiverem envolvidas, Allow-Credentials: true E uma origem específica (sem curinga). Respostas de preflight (OPTIONS) incluem Allow-Methods/Headers. Expose-Headers permite que o JS leia headers de resposta não padrão.

http
# Allow a specific origin
Access-Control-Allow-Origin: https://example.com
# Or wildcard (but credentials won't work with *)
Access-Control-Allow-Origin: *

# Allow credentials (cookies, Authorization)
Access-Control-Allow-Credentials: true

# Allowed methods (preflight response)
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

# Allowed headers (preflight response)
Access-Control-Allow-Headers: Content-Type, Authorization

# How long browser can cache preflight (seconds)
Access-Control-Max-Age: 86400

# Headers the JS can read from the response
Access-Control-Expose-Headers: X-Request-ID, X-Total-Count

Headers de cache

Cache-Control é o header de caching moderno (HTTP/1.1) com diretivas: public/private (quem pode cachear), max-age (frescor em segundos), no-cache (deve revalidar), no-store (nunca cachear), immutable (URL nunca muda). ETag e Last-Modified são validadores usados com requisições condicionais. Expires (HTTP/1.0) é um fallback. Age diz há quanto tempo uma resposta está em cache.

http
# Cache-Control directives (HTTP/1.1 - preferred)
Cache-Control: public, max-age=3600
Cache-Control: private, max-age=600
Cache-Control: no-cache              # revalidate before use
Cache-Control: no-store              # never cache
Cache-Control: must-revalidate
Cache-Control: immutable

# Validators
ETag: "abc123"                       # opaque version tag
Last-Modified: Wed, 21 Oct 2023 07:28:00 GMT

# HTTP/1.0 fallbacks (deprecated)
Expires: Wed, 21 Oct 2023 08:28:00 GMT
Pragma: no-cache

# Age: time a response has been in a cache (seconds)
Age: 120
06

Cookies e Set-Cookie

Definindo cookies (Set-Cookie)

Set-Cookie instrui o navegador a armazenar um cookie. Cada atributo controla escopo e tempo de vida: Domain/Path restringem onde é enviado; Max-Age (segundos) ou Expires definem o tempo de vida; Secure limita a HTTPS; HttpOnly bloqueia acesso do JS; SameSite controla o envio cross-site. Para apagar um cookie, defina Max-Age=0 com o mesmo Path/Domain.

http
# Basic cookie
HTTP/1.1 200 OK
Set-Cookie: session=abc123

# With attributes
Set-Cookie: session=abc123; Path=/; Domain=example.com; Max-Age=3600; HttpOnly; Secure; SameSite=Lax

# Multiple cookies = multiple Set-Cookie headers
Set-Cookie: session=abc123; HttpOnly; Secure
Set-Cookie: theme=dark; Max-Age=86400
Set-Cookie: lang=en-US; Path=/

# Deleting a cookie: set Max-Age=0 or expired Expires
Set-Cookie: session=; Max-Age=0; Path=/

Atributos de cookie

Atributos de cookie controlam segurança e escopo. Secure + HttpOnly + SameSite é a base moderna. SameSite=Lax é o padrão dos navegadores — permite cookies em navegações de nível superior, mas os bloqueia em contextos de terceiros (derrota a maioria dos CSRF). O prefixo __Host- força Path=/, sem Domain, e Secure — prevenindo injeção de cookie de subdomínio. __Secure- exige Secure.

http
# Security attributes
Secure           # only sent over HTTPS
HttpOnly         # not accessible via document.cookie (XSS protection)
SameSite=Strict  # never sent on cross-site requests
SameSite=Lax     # sent on top-level navigation (default in modern browsers)
SameSite=None    # sent cross-site (requires Secure)

# Scope attributes
Domain=example.com    # visible to subdomains too
Path=/                # visible to all paths
Path=/api             # only /api and below

# Lifetime attributes
Max-Age=3600          # seconds (preferred)
Expires=Wed, 21 Oct 2025 07:28:00 GMT  # absolute date

# __Host- and __Secure- prefixes (extra protection)
Set-Cookie: __Host-session=abc; Path=/; Secure; HttpOnly; SameSite=Lax

Enviando cookies (Cookie)

O header de requisição Cookie envia os cookies correspondentes como pares name=value (sem atributos). Cookies são enviados automaticamente pelo navegador em cada requisição correspondente. Para fetch cross-origin com cookies, o cliente deve definir credentials: 'include' E o servidor deve ecoar uma origem específica (não *) com Access-Control-Allow-Credentials: true.

http
# Browser sends stored cookies back to the server
GET /api/profile HTTP/1.1
Host: example.com
Cookie: session=abc123; theme=dark; lang=en-US

# Format: name=value pairs separated by "; "
# No attributes are sent back - only name=value

# Server reads cookies (Express.js example)
# const sessionId = req.headers.cookie
#   .split(';').find(c => c.trim().startsWith('session='))
#   .split('=')[1];

# Cross-site requests (with credentials)
fetch('https://api.example.com/data', {
  credentials: 'include'  # sends cookies cross-origin
});
# Server must respond with:
# Access-Control-Allow-Origin: https://app.example.com (specific, no *)
# Access-Control-Allow-Credentials: true

Cookie vs token

Cookies são armazenados e enviados automaticamente pelo navegador; tokens (JWT) são armazenados em JS e enviados manualmente. Cookies são vulneráveis a CSRF (mitigado por SameSite). Tokens são vulneráveis a XSS (mitigado por tempos de vida curtos e armazenamento seguro). Cookies servem para apps web de mesma origem; tokens servem para APIs e SPAs. O melhor dos dois: guarde o refresh token num cookie HttpOnly, e o access token na memória.

http
# Cookie-based auth (stateful server-side session)
POST /login HTTP/1.1
Host: example.com
Content-Type: application/json

{"user": "alice", "password": "secret"}

# Server response
HTTP/1.1 200 OK
Set-Cookie: session=abc123; HttpOnly; Secure; SameSite=Lax

# Subsequent requests carry cookie automatically
GET /api/profile HTTP/1.1
Cookie: session=abc123

# Token-based auth (stateless, e.g., JWT)
# Server response
HTTP/1.1 200 OK
Content-Type: application/json

{"token": "eyJhbGc..."}

# Subsequent requests carry token in header (manual)
GET /api/profile HTTP/1.1
Authorization: Bearer eyJhbGc...

Cookies de terceiros e SameSite

Cookies de terceiros são definidos por um domínio diferente do da página que o usuário visita — usados há muito para rastreamento e anúncios. SameSite=None+Secure é exigido para eles. Navegadores modernos (Chrome, Firefox, Safari) estão eliminando os cookies de terceiros. Alternativas incluem CHIPS (cookies Partitioned, com escopo por site de nível superior), a Storage Access API e rastreamento no servidor. ITP (Safari) os bloqueia por completo.

http
# First-party cookie: domain matches the page
Set-Cookie: session=abc; Domain=example.com
# Visiting example.com -> sent to example.com (first-party)

# Third-party cookie: embedded in another site's page
# e.g., analytics.com cookie loaded via <img> on shop.com
Set-Cookie: tracker=xyz; Domain=analytics.com; SameSite=None; Secure

# SameSite behavior:
# Strict  -> NOT sent on shop.com -> analytics.com requests
# Lax     -> NOT sent on embedded cross-site requests
#            (sent on top-level navigation)
# None    -> sent cross-site (requires Secure)

# Browsers are phasing out third-party cookies (2024+).
# Alternatives: Partitioned cookies (CHIPS)
Set-Cookie: tracker=xyz; Partitioned; Secure; SameSite=None
07

Autenticação

Basic Authentication

Basic auth envia credenciais codificadas em base64 a cada requisição. É simples e universalmente suportada, mas oferece segurança zero sem HTTPS — base64 é trivialmente decodificável. O header WWW-Authenticate desafia o cliente (navegadores mostram um diálogo nativo de login). Basic auth é rara em apps web modernas, mas comum para tokens de API e ferramentas internas.

http
# Basic auth: base64(user:pass) sent on every request
GET /api/data HTTP/1.1
Host: example.com
Authorization: Basic dXNlcjpwYXNz

# dXNlcjpwYXNz = base64("user:pass")
# In curl: curl -u user:pass https://example.com/api/data

# Server challenge (401 with WWW-Authenticate)
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Restricted Area", charset="UTF-8"

# WARNING: base64 is encoding, NOT encryption.
# Always pair Basic auth with HTTPS.

Bearer Token (OAuth 2.0)

Bearer tokens são strings opacas apresentadas como prova de autorização. O servidor só precisa validá-los — são stateless se autocontidos (JWT) ou consultados num armazenamento. OAuth 2.0 define fluxos para obter tokens (authorization code, client credentials, refresh token). Sempre envie Bearer tokens sobre HTTPS. Tokens têm tempos de vida finitos; use refresh tokens para obter novos.

http
# Bearer token: opaque string proving authorization
GET /api/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer SlAV32hkKG...

# Token obtained from OAuth 2.0 flow:
POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=alice&password=secret&client_id=...

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "SlAV32hkKG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "GmR..."
}

Estrutura do JWT

Um JWT tem três partes codificadas em base64url separadas por pontos: header (algoritmo), payload (claims) e assinatura. A assinatura prova que o token não foi adulterado. Claims comuns: sub (subject), iat (emitido em), exp (expiração), iss (emissor), aud (audiência). O payload NÃO é criptografado — nunca coloque segredos ali. Algoritmos de assinatura: HS256 (HMAC), RS256 (RSA), ES256 (ECDSA).

http
# JWT = header.payload.signature (base64url-encoded)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

# Decoded:
# Header
{"alg": "HS256", "typ": "JWT"}

# Payload (claims)
{
  "sub": "1234567890",        # subject (user id)
  "name": "Alice",
  "iat": 1516239022,          # issued at
  "exp": 1516242622,          # expiration
  "iss": "example.com",       # issuer
  "aud": "api.example.com"    # audience
}

# Signature (HMAC-SHA256 of header.payload with secret)
HMAC-SHA256(secret, "eyJhbGc...")

Validação de JWT

Validação de JWT: verifique a assinatura (captura adulteração), depois verifique as claims (exp, iss, aud). exp é a mais importante — rejeite tokens expirados com 401. JWTs são stateless: uma vez emitidos, não podem ser revogados até expirar. Para revogação, use access tokens de curta duração (5-15 min) + refresh tokens armazenados no servidor, ou mantenha uma blacklist (anula o stateless).

http
# Server-side JWT validation steps:
# 1. Parse three parts (header.payload.signature)
# 2. Verify signature using secret (HS256) or public key (RS256)
# 3. Check claims:
#    - exp (must be in future)
#    - iat (must be in past, optional)
#    - iss (must match expected issuer)
#    - aud (must match expected audience)
# 4. Check revocation list (if using short-lived + refresh)

# Common errors:
# 401 - invalid signature, expired, wrong issuer
# 401 - "Bearer" prefix missing
# 403 - valid token but lacking permission (scope)

# Token expired response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The token has expired"

Fluxo OAuth 2.0 Authorization Code

O fluxo Authorization Code é o padrão para apps web no lado do servidor. Passo 1 redireciona o usuário ao servidor de auth. Passo 2 retorna um código de curta duração ao redirect URI. Passo 3 troca o código (mais client_secret) por tokens, servidor a servidor. PKCE (Proof Key for Code Exchange) substitui o secret por um par code challenge/verifier — essencial para SPAs e apps móveis, em que o secret não pode ser armazenado com segurança.

http
# Step 1: Redirect user to authorization endpoint
GET /authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://app.com/callback&scope=read&state=random123 HTTP/1.1
Host: auth.example.com

# Step 2: User logs in & grants consent, redirected back with code
HTTP/1.1 302 Found
Location: https://app.com/callback?code=AUTH_CODE&state=random123

# Step 3: Server exchanges code for token (server-to-server)
POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https://app.com/callback

# Step 4: Token response
{"access_token": "...", "refresh_token": "...", "expires_in": 3600}

# Use PKCE for SPAs/mobile (no client_secret)
# code_challenge = base64url(SHA256(code_verifier))

API Keys

API keys são segredos opacos simples que identificam um cliente. São enviadas em headers (preferido) ou query strings (evite — aparecem em logs de URLs e proxies). API keys são stateful (o servidor as consulta) e revogáveis. Diferente de JWTs, não carregam claims — o servidor armazena as permissões. Boas práticas: faça hash das chaves em repouso, escopo-as com rigidez, rotacione-as e forneça uma UI de rotação self-service.

http
# API key in header (most common)
GET /api/data HTTP/1.1
X-API-Key: abc123def456

# API key as Bearer token
Authorization: Bearer abc123def456

# API key in query string (less secure - logged in URLs)
GET /api/data?api_key=abc123def456 HTTP/1.1

# API key in custom header with prefix
Authorization: ApiKey abc123def456

# Best practices:
# - Rotate keys periodically
# - Scope keys to specific permissions
# - Store keys hashed at rest (like passwords)
# - Never commit keys to source control
08

Content negotiation

Header Accept

O header Accept lista os media types que o cliente pode tratar, com valores de qualidade (q) expressando preferência. Curingas (text/*, */*) ampliam a correspondência. O servidor escolhe a melhor correspondência e responde com o Content-Type escolhido. Se nenhum media type casar, o servidor idealmente retorna 406, mas na prática muitas APIs caem num formato padrão.

http
# Single type
Accept: application/json

# Multiple types with preferences (q values, 0-1)
Accept: text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8

# Wildcard media types
Accept: text/*           # any text/* subtype
Accept: */*              # anything
Accept: image/png, image/*;q=0.8

# Parameters
Accept: text/html;charset=utf-8

# Server picks best match and returns it in Content-Type.
# If no match, server returns 406 Not Acceptable (or a default).

Accept-Language

Accept-Language diz ao servidor os idiomas preferidos do usuário, com valores de qualidade para ranquear. A RFC 5646 define tags de idioma (idioma[-script][-região]). O servidor responde com Content-Language. Os navegadores definem isso conforme as configurações de SO/locale do usuário. Para i18n, caia graciosamente: se o idioma pedido não estiver disponível, retorne o padrão. CDNs às vezes variam caches por Accept-Language — use o header Vary.

http
# Single language
Accept-Language: en-US

# Multiple languages with preferences
Accept-Language: en-US,en;q=0.9, zh-CN;q=0.8, fr;q=0.7, de;q=0.5

# Wildcard
Accept-Language: *

# Server responds with the selected language:
Content-Language: en-US

# RFC 5646 language tags:
# en       - language
# en-US    - language + region
# zh-Hans  - language + script (Simplified Chinese)
# es-419   - language + region (Latin America)

Accept-Encoding

Accept-Encoding lista os algoritmos de compressão que o cliente pode decodificar. O servidor escolhe um e o aplica, retornando Content-Encoding. Brotli (br) comprime texto melhor que gzip e é suportado nos navegadores modernos. zstd está emergindo com velocidade/razão ainda melhores. identity significa sem compressão. Sempre habilite compressão para respostas de texto (HTML, CSS, JS, JSON) — grande economia de banda, mas pule formatos já comprimidos (imagens, vídeo).

http
# Accepted compression algorithms
Accept-Encoding: gzip, deflate, br, zstd

# With preferences
Accept-Encoding: br;q=1.0, gzip;q=0.8, identity;q=0.5, *;q=0

# identity = no encoding (raw)
# * = any encoding not listed

# Server response
Content-Encoding: br

# Common algorithms:
# gzip     - widespread, RFC 1952
# deflate  - zlib, RFC 1950
# br       - Brotli, better for text (modern browsers)
# zstd     - Zstandard, fast + good ratio (newer)
# identity - no compression

Header Vary

O header Vary diz aos caches (navegador, CDN, proxy) quais headers de requisição afetam a resposta. Se um servidor retorna conteúdo diferente com base em Accept-Encoding, precisa Vary: Accept-Encoding para que o cache não sirva uma resposta gzip a um cliente que só aceita br. Vary demais prejudica a taxa de acerto do cache; Vary de menos causa cache poisoning (conteúdo errado servido). Vary: * efetivamente desabilita o caching.

http
# Server response telling caches to vary by Accept-Encoding
HTTP/1.1 200 OK
Content-Type: text/html
Content-Encoding: gzip
Vary: Accept-Encoding

# Vary on multiple headers
Vary: Accept-Encoding, Accept-Language

# Vary on Accept (full content negotiation)
Vary: Accept

# Vary: * means "varies on everything" (effectively no-cache)
Vary: *

# CDN/cache key includes the Vary header values.
# A gzip+en response is cached separately from a br+fr response.

Valores de qualidade (q)

Valores de qualidade (q, 0-1) expressam a força da preferência em headers da família Accept. q=1.0 é o padrão (mais preferido); q=0 significa 'inaceitável'. O servidor lista o que pode produzir, cruza com a lista do cliente e escolhe a correspondência de maior q. Especificidade desempata: application/json vence */* mesmo com o mesmo q. Três casas decimais são permitidas, mas raramente necessárias.

http
# q values appear in Accept, Accept-Language, Accept-Encoding, Accept-Charset
# Format: ;q=0.000 to ;q=1.000 (default is 1.0)

Accept: text/html;q=1.0, application/json;q=0.9, */*;q=0.1

# Meaning:
# q=1.0    - strongly preferred
# q=0.5    - acceptable
# q=0      - NOT acceptable (refuse)

# Server algorithm (RFC 7231):
# 1. List media types the server can produce
# 2. Match each against the client's Accept
# 3. Pick the match with the highest q value
# 4. Ties broken by specificity (concrete > wildcard)

# Example: client prefers JSON over XML
Accept: application/json, application/xml;q=0.5
09

Caching

Diretivas do Cache-Control

Cache-Control é o header de caching moderno, com diretivas. public/private controla quem pode cachear; max-age define o frescor em segundos; no-cache força revalidação; no-store proíbe caching; must-revalidate proíbe servir obsoleto; s-maxage define um TTL separado para caches compartilhados (CDNs). immutable diz aos navegadores que o recurso nunca muda — pule a revalidação ao recarregar. Stale-while-revalidate e stale-if-error habilitam degradação graciosa.

http
# Response directives (server -> cache)
Cache-Control: public, max-age=3600           # cacheable by all, fresh 1h
Cache-Control: private, max-age=600           # browser only, fresh 10min
Cache-Control: no-cache                       # revalidate before use
Cache-Control: no-store                       # never cache (sensitive data)
Cache-Control: must-revalidate                # never serve stale
Cache-Control: proxy-revalidate               # proxies must revalidate
Cache-Control: immutable                      # URL never changes
Cache-Control: max-age=0, must-revalidate     # always revalidate
Cache-Control: s-maxage=3600, max-age=600     # CDN caches 1h, browser 10min

# Request directives (client -> cache)
Cache-Control: no-cache                       # send request to origin
Cache-Control: no-store                       # don't store the response
Cache-Control: only-if-cached                 # only from cache

ETag e If-None-Match

ETag é uma tag de versão opaca (frequentemente um hash do conteúdo) anexada a uma resposta. Na próxima requisição, o cliente envia If-None-Match com o ETag salvo. Se o recurso não mudou, o servidor retorna 304 Not Modified sem corpo — economizando banda. ETags fortes garantem conteúdo byte-idêntico; ETags fracas (W/) permitem respostas semanticamente equivalentes (por exemplo, diferenças de espaço em branco).

http
# Server tags a response with an ETag
HTTP/1.1 200 OK
ETag: "abc123"
Content-Type: application/json

{"data": "..."}

# Client sends conditional request on next fetch
GET /api/data HTTP/1.1
If-None-Match: "abc123"

# Server compares:
# - If matches: 304 Not Modified (no body)
HTTP/1.1 304 Not Modified
ETag: "abc123"

# - If changed: 200 OK with new body + new ETag
HTTP/1.1 200 OK
ETag: "def456"

# Strong vs weak ETags:
# "abc123"      - strong (byte-identical)
# W/"abc123"    - weak (semantically equivalent)

Last-Modified e If-Modified-Since

Last-Modified é um validador baseado em timestamp. Tem precisão de 1 segundo — mudanças em menos de um segundo podem ser perdidas. If-Modified-Since dispara um 304 se não houver mudança. If-Unmodified-Since protege contra atualizações perdidas: se outro cliente modificou o recurso, o servidor retorna 412 Precondition Failed. ETag é preferido quando disponível (mais preciso), mas Last-Modified é um fallback útil.

http
# Server includes Last-Modified
HTTP/1.1 200 OK
Last-Modified: Wed, 21 Oct 2023 07:28:00 GMT

# Client sends conditional request
GET /api/data HTTP/1.1
If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT

# Server: if not modified since that time -> 304
HTTP/1.1 304 Not Modified

# Server: if modified since -> 200 with new content
HTTP/1.1 200 OK
Last-Modified: Thu, 22 Oct 2023 09:00:00 GMT

# If-Unmodified-Since (for safe updates - optimistic locking)
PUT /api/users/42 HTTP/1.1
If-Unmodified-Since: Wed, 21 Oct 2023 07:28:00 GMT
# 412 Precondition Failed if modified elsewhere

Fluxo de validação de cache

Fluxo de cache: fresco (dentro do max-age) → servido do cache, sem rede. Obsoleto (após o max-age) → requisição condicional com validadores. 304 renova o timer do cache sem baixar o corpo de novo. 200 substitui a entrada em cache. Isso corta drasticamente banda e carga na origem. Para dados que mudam com frequência, mas toleram leve obsolescência, use stale-while-revalidate.

http
# 1. First request - server sends validators
GET /api/users HTTP/1.1

HTTP/1.1 200 OK
Cache-Control: max-age=60
ETag: "v1"
Last-Modified: Wed, 21 Oct 2023 07:28:00 GMT

# 2. Within max-age (60s): cache serves directly, no network
GET /api/users  (served from cache)

# 3. After max-age: stale - revalidate (conditional GET)
GET /api/users HTTP/1.1
If-None-Match: "v1"
If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT

# 4a. Unchanged -> 304 (revalidate resets the cache timer)
HTTP/1.1 304 Not Modified
Cache-Control: max-age=60
ETag: "v1"

# 4b. Changed -> 200 with new body
HTTP/1.1 200 OK
Cache-Control: max-age=60
ETag: "v2"

Cache busting e invalidação

Cache busting: dê a assets imutáveis (JS, CSS, imagens) URLs versionadas (app.v1a2b3c.js) e cacheie-as por um ano com immutable. Ao fazer deploy, mude a URL — os navegadores buscam o arquivo novo. O ponto de entrada HTML usa no-cache para que os usuários sempre revalidem e peguem as URLs de assets novas. Esse padrão dá tanto atualizações instantâneas quanto caches de longa duração. Evite versionamento por query string (?v=123) — alguns proxies não cacheiam.

http
# Immutable assets with long cache + versioned URLs
GET /assets/app.v1a2b3c.js HTTP/1.1
HTTP/1.1 200 OK
Cache-Control: public, max-age=31536000, immutable

# When deploying a new version, the URL changes:
GET /assets/app.v4d5e6f.js HTTP/1.1
# (browser fetches new file; old one stays cached but unused)

# HTML entry point: short cache, must revalidate
GET /index.html HTTP/1.1
HTTP/1.1 200 OK
Cache-Control: no-cache
# (revalidate every time, but 304 if unchanged)

# Anti-pattern: caching HTML forever (users see stale entry)
# Anti-pattern: querying JS with ?ts=123 (defeats CDN caching)

# Manual cache purge via CDN API (vendor-specific)
10

CORS (cross-origin)

Same-Origin Policy e CORS

A Same-Origin Policy (SOP) é um modelo de segurança de navegador que impede páginas web de ler respostas cross-origin por padrão. CORS (Cross-Origin Resource Sharing) é a exceção opt-out: o servidor declara quais origens podem ler suas respostas. Origin é definida como scheme+host+porta — qualquer diferença significa cross-origin. CORS só importa para requisições baseadas em navegador; chamadas servidor a servidor são irrestritas.

http
# Same-Origin Policy (SOP): browsers block cross-origin reads by default
# Origin = scheme + host + port
# https://app.com  vs  https://api.com  -> DIFFERENT origins
# http://app.com   vs  https://app.com  -> DIFFERENT (scheme)
# https://app.com  vs  https://app.com:8443 -> DIFFERENT (port)

# CORS lets a server OPT IN to cross-origin requests
# via Access-Control-Allow-Origin response header.

# Simple cross-origin GET (no preflight)
GET /api/data HTTP/1.1
Host: api.example.com
Origin: https://app.example.com

# Server allows the origin
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com

Requisições simples (sem preflight)

Requisições simples pulam a etapa de preflight e vão direto ao servidor. As restrições são conservadoras: só GET/HEAD/POST, só headers da safelist, e só Content-Types simples. Qualquer desvio (por exemplo, Content-Type: application/json, headers personalizados, PUT/DELETE) torna a requisição 'não simples' e dispara um preflight. O servidor ainda precisa incluir headers CORS na resposta, ou o navegador bloqueia a leitura.

http
# A "simple" request is sent directly (no preflight):
# - Method: GET, HEAD, or POST
# - Only CORS-safelisted headers:
#     Accept, Accept-Language, Content-Language, Content-Type
# - Content-Type limited to:
#     application/x-www-form-urlencoded
#     multipart/form-data
#     text/plain
# - No event listeners on upload
# - No ReadableStream

# Example: simple cross-origin POST form submit
POST /api/login HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Content-Type: application/x-www-form-urlencoded

user=alice&pass=secret

# Server must respond with Allow-Origin for browser to expose response

Requisições preflight (OPTIONS)

Um preflight é uma requisição OPTIONS que o navegador envia antes de uma requisição cross-origin não simples. Verifica se a função e os headers reais são permitidos. O servidor responde com Allow-Methods e Allow-Headers. Access-Control-Max-Age cacheia o resultado do preflight (padrão 5s, navegadores limitam a 24h). Preflights adicionam latência — evite-os em caminhos quentes, mantendo requisições simples onde possível.

http
# Browser sends preflight OPTIONS before non-simple requests
OPTIONS /api/data HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Content-Type, Authorization

# Server preflight response
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400  # cache preflight for 24h

# Only then does the browser send the actual request
PUT /api/data HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Content-Type: application/json
Authorization: Bearer ...

{"key": "value"}

CORS com credenciais

Por padrão, fetches cross-origin não enviam cookies. Para incluí-los, o cliente define credentials: 'include'. O servidor deve responder com Access-Control-Allow-Credentials: true E ecoar a origem específica (não o curinga *). Sempre inclua Vary: Origin para que caches não sirvam a uma origem uma resposta negociada para outra. CORS+credenciais mal configurado é um furo de segurança — restrinja as origens a uma allowlist conhecida.

http
# Client: opt in to sending cookies/auth
fetch('https://api.example.com/data', {
  credentials: 'include'   # send cookies cross-origin
});

# Browser sends:
GET /data HTTP/1.1
Origin: https://app.example.com
Cookie: session=abc123

# Server response MUST:
# 1. Echo the SPECIFIC origin (NOT *)
# 2. Set Allow-Credentials: true
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin   # important: caches must vary by Origin

# Wildcard origin + credentials = browser blocks response
# (Access-Control-Allow-Origin: * with credentials fails)

Erros comuns de CORS

Erros de CORS aparecem no console do navegador. Os mais comuns são Allow-Origin ausente (o servidor não aderiu), curinga-com-credenciais (combinação proibida) e Allow-Headers/Methods ausentes nas respostas de preflight. CORS é imposto pelo navegador, não pelo servidor — a requisição ainda chega ao servidor, mas o navegador esconde a resposta do JS. Verifique a aba Network: se o preflight OPTIONS falha, a requisição real nunca é enviada.

http
# Error: No 'Access-Control-Allow-Origin' header
# Cause: server didn't send CORS header, or origin not allowed
# Fix: add Access-Control-Allow-Origin on the server

# Error: Credentials flag is true, but Allow-Origin is *
# Cause: wildcard not allowed with credentials
# Fix: echo the specific request Origin instead of *

# Error: preflight missing Allow-Methods / Allow-Headers
# Cause: server didn't allow the method/header
# Fix: add them to Access-Control-Allow-Methods/Headers

# Error: Allow-Origin doesn't match Origin
# Cause: server echoed a different origin (or scheme mismatch)
# Fix: dynamically echo req.headers.origin if allowlisted

# Debug:
# - Check browser DevTools Console for exact error
# - Check Network tab -> see the OPTIONS preflight response
# - Verify headers in the response
11

HTTPS e SSL/TLS

Handshake TLS (HTTPS)

HTTPS envolve o HTTP em criptografia TLS. O handshake TLS autentica o servidor (certificado), negocia a criptografia e troca chaves. TLS 1.2 leva 2 viagens; TLS 1.3 leva 1 (ou 0 com resumption). SNI (Server Name Indication) envia o hostname alvo em claro para que o servidor escolha o certificado certo — isso vaza o hostname a bisbilhoteiros; ECH (Encrypted Client Hello) o criptografa.

http
# HTTPS = HTTP over TLS
# 1. TCP connection (port 443)
# 2. TLS handshake:
ClientHello -> server
  - supported TLS versions, cipher suites, extensions
  - SNI: hostname (example.com)
ServerHello + Certificate + ServerHelloDone <- server
  - selected cipher, certificate (public key)
ClientKeyExchange + ChangeCipherSpec -> server
  - encrypted pre-master secret (RSA) or ECDHE params
ChangeCipherSpec + Finished <- server
# 3. Encrypted HTTP exchange begins
GET /page HTTP/1.1
Host: example.com

# TLS 1.3 collapses this to 1 round trip (1-RTT)
# 0-RTT resumption for returning connections

Conexão HTTPS

HTTPS é HTTP sobre TLS, tipicamente na porta 443. As mensagens HTTP em si não mudam — TLS apenas criptografa o tráfego TCP subjacente. Para impor HTTPS, redirecione HTTP→HTTPS (301) e defina o header HSTS para que os navegadores lembrem de usar HTTPS pela duração especificada. Listas de preload HSTS (mantidas pelos navegadores) fixam esse comportamento, para que até a primeira requisição vá por HTTPS.

http
# HTTP on port 80 (plaintext)
GET /page HTTP/1.1
Host: example.com

# HTTPS on port 443 (TLS-encrypted)
# Same HTTP messages, but the wire traffic is encrypted.
GET /page HTTP/1.1
Host: example.com

# Force HTTPS via redirect
HTTP/1.1 301 Moved Permanently
Location: https://example.com/page

# Force HTTPS via HSTS (browser remembers)
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

# Modern browsers default to https:// for bare domains
# (some even refuse plain HTTP for sensitive endpoints)

Certificados

Certificados X.509 vinculam uma chave pública a um domínio, assinados por uma Certificate Authority (CA). A cadeia de confiança vai do certificado do servidor, por intermediários, até uma CA raiz pré-instalada no navegador. Os navegadores verificam a cadeia, a data de expiração e que o SAN (Subject Alternative Name) corresponde ao hostname pedido. Certificados wildcard (*.example.com) e multi-domínio (múltiplos SANs) cobrem múltiplos hostnames.

http
# X.509 certificate contains:
# - Subject: example.com (CN is deprecated; use SAN)
# - Subject Alternative Name (SAN): example.com, www.example.com
# - Issuer: Let's Encrypt / DigiCert (CA)
# - Validity: Not Before / Not After
# - Public key (RSA or ECDSA)
# - Signature by CA

# Chain of trust:
# Root CA (self-signed, in browser trust store)
#   -> Intermediate CA
#     -> Server cert (your domain)

# Server sends leaf + intermediate during handshake.
# Browser verifies: signature chain back to a trusted root.

# Inspect a cert:
openssl s_client -connect example.com:443 -showcerts
openssl x509 -in cert.pem -text -noout

HSTS (HTTP Strict Transport Security)

HSTS diz aos navegadores para sempre usar HTTPS num domínio, prevenindo ataques de SSL-stripping. max-age é em segundos (1 ano = 31536000). includeSubDomains estende aos subdomínios. preload submete o domínio a uma lista fixa dos navegadores, para que até a primeira visita seja HTTPS — proteção forte, mas difícil de desfazer (a remoção leva meses). Sempre redirecione HTTP→HTTPS primeiro, depois adicione HSTS, e opcionalmente preload.

http
# Tell browser to use HTTPS for 6 months
Strict-Transport-Security: max-age=15768000

# Include subdomains
Strict-Transport-Security: max-age=15768000; includeSubDomains

# Submit to preload list (browsers hardcode the domain)
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

# Effects:
# - http://example.com -> browser rewrites to https://
# - Self-signed cert -> browser blocks (no override)
# - prevents SSL stripping attacks (downgrade to HTTP)

# Preload list: https://hstspreload.org
# Once preloaded, removal is slow and difficult.

Versões e cifras TLS

Desabilite SSLv2/v3 e TLS 1.0/1.1 — têm vulnerabilidades conhecidas (POODLE, BEAST). TLS 1.3 (2018) é o padrão moderno: handshake mais rápido, remove cifras fracas, impõe forward secrecy. TLS 1.2 com ECDHE + AES-GCM é aceitável. Use ferramentas como SSL Labs para avaliar sua configuração. Forward secrecy (ECDHE) garante que o tráfego passado permaneça criptografado mesmo se a chave privada vazar depois.

http
# TLS versions (deprecate old ones!)
# SSLv2, SSLv3  - BROKEN (POODLE), disable
# TLS 1.0, 1.1  - deprecated (2020), disable
# TLS 1.2       - widely supported, OK
# TLS 1.3       - fastest, most secure (preferred)

# Modern cipher suites (TLS 1.3):
# TLS_AES_256_GCM_SHA384
# TLS_CHACHA20_POLY1305_SHA256
# TLS_AES_128_GCM_SHA256

# TLS 1.2 recommended:
# ECDHE-ECDSA-AES256-GCM-SHA384 (forward secrecy + AEAD)
# ECDHE-RSA-AES256-GCM-SHA384

# Server config (nginx example)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;

# Test: https://www.ssllabs.com/ssltest/
12

HTTP/2

Recursos do HTTP/2

HTTP/2 mantém a semântica HTTP (funções, códigos de status, headers), mas muda o formato do fio para frames binários. Vitórias-chave: multiplexação de muitas requisições sobre uma conexão TCP (sem bloqueio head-of-line no nível HTTP), compressão de headers HPACK e priorização de streams. Negociado via ALPN sobre TLS (o mais comum) ou upgrade h2c sobre texto puro. Server Push foi descontinuado em 2022 por baixo desempenho no mundo real.

http
# HTTP/2 (RFC 9113, 2015) - binary, multiplexed
# - Binary framing (not text)
# - Multiplexing: many streams over 1 TCP connection
# - Header compression (HPACK)
# - Server Push (deprecated in 2022)
# - Stream prioritization
# - Single connection per origin

# Negotiation:
# - Over TLS: ALPN extension advertises "h2"
# - Over plaintext: h2c upgrade (rare in practice)

#curl with HTTP/2:
curl -v --http2 https://example.com
# (Connection header shows HTTP/2)

# Backward compatible: same methods, status codes, headers, semantics
# Only the wire format changes.

Multiplexação

Multiplexação é o recurso de destaque do HTTP/2. Muitos streams compartilham uma conexão TCP, com frames intercalados — acabou o limite de 6 conexões por origem, sem bloqueio head-of-line na camada HTTP. Isso elimina hacks do HTTP/1.1 como domain sharding, concatenação de arquivos e inlining de imagens. Nota: o bloqueio head-of-line no nível TCP ainda existe (um pacote perdido trava os streams até a retransmissão) — isso é o que o HTTP/3 resolve com QUIC.

http
# HTTP/1.1: 6 parallel connections per origin, each request blocks its connection
# (head-of-line blocking at the HTTP level)

# HTTP/2: 1 connection, many parallel streams
# Each request/response is a stream with a unique ID.

# Frames carry data for multiple streams interleaved:
# Stream 1: HEADERS, DATA (request 1)
# Stream 3: HEADERS, DATA (request 2)
# Stream 5: HEADERS, DATA (request 3)
# Server responds with interleaved frames on each stream.

# Browser opens one TCP+TLS connection per origin,
# then sends all requests as concurrent streams.

# Eliminates: domain sharding, concatenation, inlining
# (those were HTTP/1.1 optimization hacks)

Server Push (descontinuado)

Server Push permitia que o servidor enviasse recursos antes de o cliente pedir. Em teoria, economizava uma viagem para assets críticos. Na prática, foi descontinuado em 2022: o servidor não pode conhecer o estado do cache do cliente, então empurra demais, frequentemente desperdiçando banda. Navegadores agora ignoram frames PUSH_PROMISE. Alternativas modernas: <link rel=preload> no HTML, ou 103 Early Hints (o servidor envia dicas de preload antes da resposta final).

http
# Server proactively sends resources the client will need
GET /index.html HTTP/2
Host: example.com

HTTP/2 200 OK
Content-Type: text/html
Link: </style.css>; rel=preload; as=style

# Server then pushes style.css on a new stream
PUSH_PROMISE (stream 2, /style.css)
<headers + body of /style.css>

# Then the actual /index.html body follows.

# DEPRECATED (2022): browsers ignore it because:
# - Client cache might already have the asset
# - Server can't know what client has cached
# - Net performance negative in real deployments

# Modern alternative: <link rel="preload" href="...">
# or 103 Early Hints

Priorização de streams

HTTP/2 permitia que clientes expressassem prioridade de stream via uma árvore de dependências com pesos. O servidor usava isso para alocar banda: por exemplo, CSS antes de imagens. A RFC 9113 (2022) removeu o frame explícito PRIORITY, deixando o agendamento ao servidor — muitos implementaram o seu. O Extensible Prioritization Scheme (RFC 9218) é uma alternativa moderna opcional. Priorização importa mais em conexões lentas.

http
# HTTP/2 streams have priority (weight + dependency tree)
# Originally: client sends PRIORITY frames
# Client says: "CSS (stream 3) is more important than image (stream 5)"

# PRIORITY frame (original model):
# - stream dependency (parent)
# - weight (1-256)

# RFC 9113 (2022) removed explicit prioritization
# - Leaves it to the server
# - Many servers implement their own scheduler

# Practical effect: server allocates bandwidth
# - HTML, CSS, JS -> high priority
# - Images, fonts -> lower priority
# - Critical render path optimized

# Clients can still signal via Extensible Prioritization Scheme
# (RFC 9218) - optional.

Compressão de headers HPACK

HPACK comprime headers HTTP usando uma tabela estática de headers comuns, uma tabela dinâmica por conexão que aprende valores recentes, e codificação Huffman. Isso corta drasticamente o overhead — um cookie de 1KB enviado a cada requisição vira uma pequena referência indexada. HPACK é cuidadosamente desenhado para evitar os ataques de oráculo de compressão CRIME/BREACH que assolaram a compressão TLS anterior. HTTP/3 usa um esquema parecido chamado QPACK.

http
# HTTP/1.1: headers sent as plaintext on every request (redundant)
# Cookies alone can exceed 1KB per request.

# HTTP/2: HPACK compresses headers
# - Static table: 61 common headers (e.g., :method GET)
# - Dynamic table: per-connection, learns recently sent headers
# - Huffman coding for strings

# Example: first request sends full User-Agent (200 bytes)
# Subsequent requests reference the dynamic table entry (2 bytes)

# Indexed header representation:
# 1 bit set + index -> "use entry N"

# Literal with incremental indexing:
# "add this to the dynamic table for future reuse"

# Security: CRIME attack exploited compression oracles.
# HPACK mitigates by never compressing sensitive + attacker-controlled
# data together.
13

HTTP/3 e QUIC

Protocolo QUIC

QUIC é um protocolo de transporte sobre UDP que integra TLS 1.3 e fornece streams confiáveis e multiplexados. Mover para UDP permite que o QUIC evolua mais rápido que o TCP do kernel. Vantagens-chave: sem bloqueio head-of-line no nível TCP (um pacote perdido trava apenas um stream), resumption 0-RTT para conexões de retorno, e migração de conexão (um celular trocando de Wi-Fi para dados móveis mantém a conexão). HTTP/3 roda sobre QUIC.

http
# QUIC = Quick UDP Internet Connections (Google, then IETF)
# - Transport protocol over UDP (not TCP)
# - Built-in TLS 1.3 encryption
# - Multiple streams, independent per-stream delivery
# - 0-RTT connection resumption
# - Connection migration (survives IP changes)
# - Better loss recovery than TCP

# Why UDP? TCP is in the kernel and hard to evolve.
# QUIC moves reliability + congestion control to user space.

# Wire format: UDP packets containing QUIC packets
# - Initial, Handshake, 1-RTT, 0-RTT packets
# - Frames carry stream data, acks, flow control

# Negotiation:
# Server advertises HTTP/3 via Alt-Svc header on HTTP/2 response:
Alt-Svc: h3=":443"; ma=86400
# Browser caches this and uses HTTP/3 next time.

Recursos do HTTP/3

HTTP/3 preserva a semântica HTTP, mas roda sobre QUIC em vez de TCP. A grande vitória: sem bloqueio head-of-line. Em HTTP/2, um único pacote TCP perdido trava os streams multiplexados até a retransmissão; em HTTP/3, apenas o stream afetado espera. Mais resumption 0-RTT e migração de conexão. O custo: mais CPU (QUIC em espaço de usuário) e UDP às vezes bloqueado/limitado por redes. A adoção cresce — a maioria dos grandes sites suporta.

http
# HTTP/3 (RFC 9114, 2022) - HTTP semantics over QUIC
# Same methods, status codes, headers as HTTP/2
# - Binary framing (similar to HTTP/2)
# - Multiplexing over QUIC streams (no HoL blocking!)
# - QPACK header compression (HPACK variant)
# - 0-RTT for returning clients
# - Connection migration

# Loss recovery: per-stream, not per-connection
# A lost packet stalls only that stream, others continue.

# Head-of-line blocking eliminated at the transport layer:
# HTTP/2: lost TCP packet blocks ALL streams (kernel retransmit)
# HTTP/3: lost QUIC packet blocks only that stream

# curl with HTTP/3 (requires special build):
curl -v --http3 https://example.com

Resumption de conexão 0-RTT

0-RTT permite que clientes que retornam enviem dados no seu primeiro voo (nenhuma viagem antes da requisição). Isso corta dezenas a centenas de milissegundos em visitas repetidas. A pegadinha: os dados iniciais podem ser reproduzidos por um atacante, então devem se limitar a operações idempotentes (GET, HEAD, PUT/DELETE se idempotente). Servidores devem rejeitar 0-RTT para POST e outros funções que mudam estado. Mecanismos anti-replay adicionam complexidade.

http
# TLS 1.3 + QUIC: 0-RTT resumption for returning clients
# First visit: full handshake (1-RTT in TLS 1.3)
Client -> Server: ClientHello + key share
Server -> Client: ServerHello + key share + Finished
Client -> Server: Finished + first HTTP request

# Returning visit (0-RTT):
Client -> Server: ClientHello + early data (HTTP request)
# Server can respond immediately, no round trip!

# Trade-offs:
# + Saves 1 RTT on subsequent visits (faster page loads)
# - Vulnerable to replay attacks on early data
# - Only safe for idempotent methods (GET, HEAD)
# - Server should reject 0-RTT for non-idempotent requests

# Configure carefully:
# - Limit early data to safe methods
# - Use anti-replay mechanisms

Migração de conexão

Conexões QUIC são identificadas por um connection ID em vez da tupla 4 de IP/porta. Isso significa que uma conexão sobrevive a mudanças de IP — um celular trocando de Wi-Fi para dados móveis, ou um laptop movendo-se entre redes, mantém a conexão viva. O servidor valida o novo caminho com PATH_CHALLENGE/PATH_RESPONSE. O TCP não pode fazer isso porque o kernel identifica conexões pela tupla 4. Grande vitória para mobile.

http
# TCP connection identified by 4-tuple:
# (src IP, src port, dst IP, dst port)
# If your phone switches Wi-Fi -> cellular, IP changes ->
# the TCP connection dies. Browser must reconnect.

# QUIC uses a connection ID (random, in every packet).
# The 4-tuple can change mid-connection; the connection ID
# identifies the connection.

# Scenario:
# 1. Phone on Wi-Fi, downloading a large file over HTTP/3
# 2. Phone walks out, switches to cellular
# 3. Packets now arrive from a new IP, same connection ID
# 4. Server continues serving the same connection!
# 5. No reconnect, no re-handshake, no failed download.

# Validation: server sends PATH_CHALLENGE, client replies PATH_RESPONSE.

HTTP/1.1 vs HTTP/2 vs HTTP/3

HTTP/1.1 é texto sobre TCP com 6 conexões paralelas. HTTP/2 é binário sobre TCP com multiplexação (mas bloqueio HoL no nível TCP). HTTP/3 é binário sobre QUIC, sem bloqueio HoL, com criptografia obrigatória, 0-RTT e migração de conexão. A adoção é incremental: servidores anunciam HTTP/3 via o header Alt-Svc nas respostas HTTP/2, e navegadores migram na próxima visita. Os três compartilham a semântica HTTP.

http
# Feature comparison
# Property         | HTTP/1.1     | HTTP/2       | HTTP/3
# -----------------+--------------+--------------+--------------
# Transport        | TCP          | TCP          | QUIC (UDP)
# Format           | Text         | Binary       | Binary
# Multiplexing     | No (6 conns) | Yes          | Yes
# HoL blocking     | HTTP-level   | TCP-level    | None
# Header compress  | No           | HPACK        | QPACK
# Server Push      | No           | Yes (deprecated) | No
# Encryption       | Optional     | Optional     | Mandatory (TLS 1.3)
# 0-RTT            | No           | No           | Yes
# Connection migration | No       | No           | Yes
# Handshake RTT    | 1+           | 1+           | 0-1 (with resumption)

# Most sites today: HTTP/2 over TLS, with HTTP/3 available via Alt-Svc
14

Redirecionamentos (3xx)

301 vs 302

301 significa permanente: navegadores cacheiam o redirecionamento, favoritos se atualizam, e o valor de links de SEO passa para a nova URL. 302 significa temporário: nada é cacheado, o SEO fica com o original. Historicamente, ambos convertiam POST→GET (uma violação da spec que virou de facto). Para preservar estritamente a função, use 307 (temporário) ou 308 (permanente). Para migrações de SEO use 301; para redirecionamentos de login use 302 ou 307.

http
# 301 Moved Permanently
HTTP/1.1 301 Moved Permanently
Location: https://newsite.com/page
# - Permanent; browser & SEO caches it
# - Link juice transfers to new URL (SEO)
# - Bookmark updates
# - HTTP/1.1 spec: should preserve method, but historically
#   POST -> GET (causing data loss)

# 302 Found
HTTP/1.1 302 Found
Location: /login
# - Temporary
# - Don't update bookmarks
# - SEO link juice stays with original URL
# - HTTP/1.1 spec: should preserve method, but historically
#   POST -> GET

# Use 301 for permanent moves (site migrations).
# Use 302 for temporary redirects (login flows, A/B tests).

307 vs 308

307 e 308 são as contrapartes preservadoras de função de 302 e 301. Corrigem o bug histórico de conversão POST→GET. 307 é temporário, 308 é permanente — ambos mantêm a função e o corpo originais. Use-os ao redirecionar requisições não-GET, especialmente em APIs, em que uma conversão POST→GET descartaria silenciosamente o corpo. 308 é a escolha moderna para mudanças permanentes de endpoint de API.

http
# 307 Temporary Redirect (HTTP/1.1, method-preserving)
HTTP/1.1 307 Temporary Redirect
Location: /new-endpoint
# - Temporary
# - Method PRESERVED: POST stays POST, body stays intact
# - Browser prompts before re-issuing POST to different host

# 308 Permanent Redirect (RFC 7538)
HTTP/1.1 308 Permanent Redirect
Location: https://newsite.com/api
# - Permanent
# - Method PRESERVED
# - Like 301 but without the POST->GET conversion

# When to use:
# - 307: temporary redirect that must preserve method
# - 308: permanent redirect that must preserve method
#   (e.g., API endpoint moved, clients still POSTing)

# Most browsers support both since ~2015.

303 See Other (padrão PRG)

303 See Other diz explicitamente ao navegador para seguir com um GET — a ferramenta certa para o padrão Post/Redirect/Get (PRG). Depois de processar um POST, redirecione com 303 para uma página GET. Se o usuário atualizar, ele refaz o GET seguro (não o POST), evitando envios de formulário duplicados. Use 303 para PRG, 307/308 quando precisar preservar a função original, 301/302 para navegação simples.

http
# 303 See Other - explicitly converts to GET
HTTP/1.1 303 See Other
Location: /success
# - Always converts to GET (no body)
# - Used in Post/Redirect/Get (PRG) pattern

# PRG pattern: avoid double-submit on refresh
# 1. User submits form
POST /checkout HTTP/1.1
Host: shop.com
Content-Type: application/x-www-form-urlencoded

item=book&qty=1

# 2. Server processes, redirects to a GET page
HTTP/1.1 303 See Other
Location: /order/123/confirmation

# 3. Browser issues GET (safe to refresh)
GET /order/123/confirmation HTTP/1.1
Host: shop.com

HTTP/1.1 200 OK
# "Order confirmed!"

Cadeias e loops de redirecionamento

Cadeias de redirecionamento adicionam latência (cada salto = viagem de ida e volta) e devem ser achatadas — aponte a URL original diretamente ao destino final. Loops de redirecionamento são fatais: navegadores os detectam após alguns saltos e mostram uma página de erro. Causas comuns: desconfiguração HTTPS↔HTTP atrás de um balanceador (use X-Forwarded-Proto), ou conflitos de barra final. HSTS evita loops de redirecionamento HTTP→HTTPS fazendo o navegador reescrever internamente.

http
# Redirect chain: A -> B -> C
GET /a  -> 301 -> /b
GET /b  -> 301 -> /c
GET /c  -> 200 OK

# Each hop adds a round trip; chains hurt performance.
# Browsers cap redirects (typically 20), then error.

# Redirect loop (fatal):
GET /a -> 302 -> /b
GET /b -> 302 -> /a
GET /a -> 302 -> /b  (browser detects loop, shows error)

# Common cause: HTTPS <-> HTTP loop
# Server A redirects HTTP -> HTTPS
# Server B (behind TLS terminator) sees HTTP internally,
# redirects to HTTPS again -> loop

# Fix: trust X-Forwarded-Proto, or use HSTS instead of redirects

# Common cause: trailing slash mismatch
# /api/users -> 301 -> /api/users/ -> 301 -> /api/users/
# (server config bug)

Casos de uso comuns de redirecionamento

Casos de uso comuns de redirecionamento: HTTP→HTTPS (301), domínio raiz↔www (301), migrações de URL antiga→nova (301), redirecionamentos de login (302/303), padrão PRG (303), mudanças de endpoint de API (308) e fallbacks de origem de CDN. Sempre prefira 301/308 para mudanças permanentes, para que caches e SEO se atualizem. Use HSTS em vez de redirecionamentos HTTP→HTTPS onde possível — evita a viagem do redirecionamento nas visitas seguintes.

http
# 1. HTTP -> HTTPS upgrade
HTTP/1.1 301 Moved Permanently
Location: https://example.com/

# 2. www -> apex (or vice versa)
HTTP/1.1 301 Moved Permanently
Location: https://example.com/

# 3. Old URL -> new URL (site migration)
HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-page

# 4. Login required (temporary)
HTTP/1.1 302 Found
Location: /login?return=/dashboard

# 5. POST form -> confirmation (PRG)
HTTP/1.1 303 See Other
Location: /success

# 6. API endpoint moved (preserve method)
HTTP/1.1 308 Permanent Redirect
Location: /v2/users

# 7. CDN origin fallback (when content not cached)
HTTP/1.1 302 Found
Location: https://origin.example.com/asset
15

Content types (MIME)

MIME types comuns

MIME types (media types) descrevem o formato de um corpo. Consistem de type/subtype e parâmetros opcionais (charset, boundary). Tipos comuns: text/html para páginas, application/json para APIs, image/* e video/* para mídia. application/octet-stream é o fallback para dados binários desconhecidos — navegadores baixam em vez de tentar renderizar. A IANA mantém o registro oficial.

http
# Text
text/html                    # HTML pages
text/plain                   # plain text
text/css                     # stylesheets
text/csv                     # comma-separated values
text/javascript              # JavaScript (legacy, was application/javascript)

# Application
application/json             # JSON
application/xml              # XML
application/javascript       # JavaScript (modern, text/javascript also OK)
application/pdf              # PDF
application/zip              # ZIP archive
application/octet-stream     # binary (unknown type, forces download)
application/x-www-form-urlencoded  # form data
application/ld+json          # JSON-LD (linked data)

# Image
image/jpeg, image/png, image/gif, image/webp, image/svg+xml, image/avif

# Audio/Video
audio/mpeg, audio/ogg, video/mp4, video/webm

# Multipart
multipart/form-data          # file uploads
multipart/byteranges         # partial content

Header Content-Type

O header Content-Type declara o MIME type do corpo. Para tipos de texto, charset especifica a codificação (o padrão para text/* é ISO-8859-1; sempre defina UTF-8 explicitamente). Para corpos multipart, boundary separa as partes. Navegadores podem 'farejar' o tipo se estiver ausente ou vago — previna com X-Content-Type-Options: nosniff, que os força a honrar o tipo declarado (hardening de segurança contra XSS via uploads de arquivos).

http
# Response Content-Type
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

# Request Content-Type (for bodies)
POST /api/users HTTP/1.1
Content-Type: application/json

{"name": "Alice"}

# charset parameter (text types)
Content-Type: text/html; charset=UTF-8

# boundary parameter (multipart)
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

# X-Content-Type-Options: nosniff
# tells browser not to sniff/override the declared type

multipart/form-data

multipart/form-data codifica múltiplas partes (campos e arquivos) num único corpo, separadas por um boundary. Cada parte tem seu próprio Content-Disposition (com filename opcional) e Content-Type. É o formato que os navegadores usam ao enviar formulários com inputs de arquivo. É a única forma prática de enviar arquivos via formulários HTML, embora para APIs, base64-em-JSON ou PUT direto a uma URL de armazenamento seja frequentemente mais simples.

http
# File upload form
POST /upload HTTP/1.1
Content-Type: multipart/form-data; boundary=----boundary123

------boundary123
Content-Disposition: form-data; name="title"

My Photo
------boundary123
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

<binary JPEG bytes>
------boundary123--

# Each part has its own headers (Content-Disposition, Content-Type).
# Final boundary has trailing --.
# Used for file uploads (browsers' <input type="file">).
# Less efficient than JSON for plain fields - overhead per part.

application/json

application/json é o formato dominante de API — leve, legível por humanos e suportado nativamente em toda linguagem. JSON é UTF-8 por padrão (o parâmetro charset é redundante, mas inofensivo). Media types específicos de fornecedor (application/vnd.api+json, application/vnd.github.v3+json) habilitam versionamento e negociação de perfil. A RFC 7807 (application/problem+json) padroniza respostas de erro.

http
# Most common API Content-Type
POST /api/users HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "name": "Alice",
  "age": 30,
  "tags": ["admin", "user"],
  "metadata": null
}

# Variants:
# application/json             - standard
# application/json; charset=utf-8  - JSON is UTF-8 by default, charset is redundant
# application/ld+json          - JSON-LD (linked data with @context)
# application/vnd.api+json     - JSON:API spec
# application/problem+json     - RFC 7807 problem details for errors

# Vendor types: application/vnd.company.v1+json
# (custom versioned JSON)

Parâmetro charset

O parâmetro charset declara a codificação do texto. Sempre defina-o para tipos text/* — o padrão ISO-8859-1 causa mojibake para caracteres não-ASCII. UTF-8 é a melhor escolha universal. Para JSON, charset é redundante (JSON é UTF-8 por spec). Para XML, a spec assume UTF-8, mas declará-lo explicitamente evita o overhead de sniffing de BOM. Charsets incompatíveis produzem caracteres ilegíveis.

http
# charset specifies the text encoding
Content-Type: text/html; charset=UTF-8      # preferred
Content-Type: text/html; charset=iso-8859-1 # legacy

# For JSON, charset is redundant (JSON spec mandates UTF-8)
Content-Type: application/json              # correct
Content-Type: application/json; charset=utf-8  # harmless but redundant

# Default charsets (when omitted):
# text/*                  -> ISO-8859-1 (legacy, problematic)
# application/json        -> UTF-8 (mandatory per spec)
# application/xml         -> UTF-8 (per XML spec)

# Always declare charset for text types to avoid mojibake.
# Mismatched charset = broken characters.

# In HTML, also declare in the document:
<meta charset="UTF-8">
16

Transferência chunked

Transfer-Encoding: chunked

A codificação de transferência chunked permite que o servidor faça streaming de um corpo sem conhecer seu comprimento total antecipadamente. Cada chunk é prefixado por seu comprimento em hex, seguido de CRLF, os dados e CRLF. Um chunk de comprimento zero sinaliza o fim. Essencial para respostas geradas dinamicamente (renderização de templates, consultas de banco) em que o tamanho só é conhecido quando os dados são produzidos. HTTP/2 e HTTP/3 não usam encoding chunked — têm seu próprio framing.

http
# When the server doesn't know the final Content-Length
# (e.g., streaming, dynamically generated content),
# it sends the body in chunks.

HTTP/1.1 200 OK
Content-Type: text/plain
Transfer-Encoding: chunked

4

Wiki

6

pedia 

E

in chunks.

0




# Each chunk: <hex-length>
<data>

# Final chunk: 0
 (zero length)
# Then optional trailer headers + final 

Respostas em streaming

Respostas em streaming usam encoding chunked para empurrar dados incrementalmente. Server-Sent Events (SSE) é o padrão canônico: o servidor mantém a conexão aberta e escreve eventos como 'data: <payload> '. A API EventSource do navegador os recebe conforme chegam. Outros usos: renderização progressiva de HTML (flush à medida que vai), arrays JSON grandes, tail de logs. Garanta que nenhum proxy intermediário bufferize a resposta — defina X-Accel-Buffering: no para nginx.

http
# Server-Sent Events (SSE): one-way streaming over HTTP
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Transfer-Encoding: chunked

data: {"msg": "hello"}


data: {"msg": "world"}


data: {"msg": "done"}



# Each event: "data: <payload>

"
# Browser keeps the connection open via EventSource API.

# Other streaming patterns:
# - Server-side rendering: flush HTML as it's generated
# - Large JSON: stream array elements
# - Logs tailing: continuous chunk stream

# Don't buffer: set X-Accel-Buffering: no (nginx)

Headers de trailer

Headers de trailer são enviados após o corpo quando se usa encoding chunked. São úteis para estatísticas resumo computadas durante o streaming — por exemplo, uma contagem de linhas, um checksum ou a duração do processamento. O header Trailer anuncia quais trailers aparecerão. Alguns headers são proibidos como trailers (Host, Content-Length, Transfer-Encoding, headers de auth) porque afetam o framing da conexão. O suporte dos clientes é irregular — muitos os ignoram.

http
# Trailer headers are sent AFTER the body (with chunked encoding)
HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Trailer: X-Total-Count, X-Duration

5

{"a":1

5

,"b":2

0

X-Total-Count: 2

X-Duration: 0.045s




# Use case: compute summary stats during streaming
# (e.g., total count, checksum) and send at the end.

# The "Trailer" header declares which trailers to expect.
# Some headers are forbidden as trailers:
# - Transfer-Encoding, Content-Length, Host
# - Authentication-related headers

Content-Length vs chunked

Content-Length diz ao cliente o tamanho exato do corpo antecipadamente — simples, habilita barras de progresso e permite reutilizar a conexão de forma limpa. Encoding chunked permite fazer streaming sem conhecer o tamanho. Você deve usar um ou outro (ou fechar a conexão no fim). Enviar ambos é ambíguo; por spec, chunked vence, mas clientes antigos podem se comportar mal. Para arquivos estáticos, sempre use Content-Length; para dinâmico/streaming, use chunked.

http
# Content-Length: known body size up front
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 11

Hello World

# Pros: simple, allows progress bars, enables persistent conn reuse
# Cons: requires knowing the size before sending

# Transfer-Encoding: chunked: stream without knowing size
HTTP/1.1 200 OK
Content-Type: text/plain
Transfer-Encoding: chunked

5
Hello

6
 World

0



# Pros: can stream as data is produced
# Cons: no progress bar, slightly more overhead per chunk

# Rule: you must use ONE of these (or close the connection).
# Using both is ambiguous - chunked wins per spec but is buggy in old clients.

Streaming em HTTP/2 (sem chunked)

HTTP/2 e HTTP/3 não usam encoding chunked — têm seu próprio framing binário. Frames DATA carregam os bytes do corpo; o flag END_STREAM sinaliza o fim. Isso dá a mesma capacidade de streaming sem o overhead por chunk do framing de comprimento em hex. O header Transfer-Encoding é ilegal em HTTP/2 (RFC 9113). Content-Length ainda é permitido, mas opcional. A semântica do streaming é preservada; só o mecanismo do fio muda.

http
# HTTP/2 and HTTP/3 don't use Transfer-Encoding: chunked.
# They have their own framing: DATA frames carry body bytes,
# END_STREAM flag marks the end.

# In HTTP/2, "streaming" means sending multiple DATA frames
# on a single stream, with the END_STREAM flag on the last.

# Server push of partial response:
# HEADERS frame (status, headers)
# DATA frame (chunk 1)
# DATA frame (chunk 2)
# DATA frame + END_STREAM (chunk 3, final)

# Effect: same streaming behavior as chunked,
# but at the framing layer, not the encoding layer.

# Transfer-Encoding header is illegal in HTTP/2.
# Content-Length is allowed but optional.
17

Requisições Range

Header Range

Requisições Range permitem que um cliente busque parte de um recurso — essenciais para downloads retomáveis, seeking de vídeo e downloads paralelos em chunks. O header Range especifica faixas de bytes. O servidor responde com 206 Partial Content e um header Content-Range mostrando o que retornou. Se o servidor não suportar faixas, ignora o header e retorna 200 com o corpo inteiro. Sempre verifique Accept-Ranges primeiro.

http
# Request a portion of a resource (e.g., resume downloads, video seeking)
GET /video.mp4 HTTP/1.1
Host: example.com
Range: bytes=0-1023        # first 1024 bytes

# Server response: 206 Partial Content
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/1048576
Content-Length: 1024
Content-Type: video/mp4

<1024 bytes of video>

# Range formats:
Range: bytes=0-1023        # bytes 0 through 1023
Range: bytes=1024-         # from byte 1024 to end
Range: bytes=-1024         # last 1024 bytes
Range: bytes=0-1023,2048-3071  # multiple ranges (multipart response)

Header Accept-Ranges

O header Accept-Ranges anuncia se o servidor suporta requisições de faixa. bytes significa sim; none (ou ausência) significa não. Clientes devem verificar antes de confiar no Range — um servidor que ignora o Range retornará o corpo inteiro com 200. Navegadores usam isso automaticamente para seeking de <video> (saltar a um timestamp = requisição de faixa) e downloads retomáveis. A maioria das CDNs e servidores estáticos suporta faixas; endpoints dinâmicos frequentemente não.

http
# Server advertises range support
HTTP/1.1 200 OK
Accept-Ranges: bytes        # supports byte-range requests
Content-Length: 1048576

# Server doesn't support ranges
HTTP/1.1 200 OK
Accept-Ranges: none

# (or omit the header entirely - same as "none")

# Client checks before sending Range:
# 1. HEAD or GET request to inspect Accept-Ranges
# 2. If "bytes", send Range: bytes=...
# 3. If "none" or missing, expect 200 with full body

# Browsers handle this transparently for video/audio,
# resumable downloads, and PDF preview.

Resposta parcial (206)

206 Partial Content é a resposta a uma requisição de faixa bem-sucedida. Content-Range mostra a unidade (bytes), a faixa retornada e o tamanho total. Se a faixa pedida excede o recurso, o servidor retorna 416 Range Not Satisfiable. If-Range torna a faixa condicional: se o validador (ETag ou data) casar, retorna 206; se o recurso mudou, retorna 200 com o corpo inteiro — prevenindo problemas de corrupção parcial.

http
# Single range request
GET /file.bin HTTP/1.1
Range: bytes=100-199

# 206 Partial Content
HTTP/1.1 206 Partial Content
Content-Range: bytes 100-199/1024
Content-Length: 100
Content-Type: application/octet-stream

<100 bytes>

# Content-Range format: <unit> <start>-<end>/<total>
# total can be "*" if unknown (streaming)

# If range is out of bounds:
# Range: bytes=1000-2000 on a 500-byte file ->
HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */500

# If-Range: only return range if validator still matches
GET /file.bin HTTP/1.1
Range: bytes=0-1023
If-Range: "etag123"
# If etag matches: 206 (partial)
# If etag differs: 200 (full body, resource changed)

Requisições multi-faixa

Requisições multi-faixa pedem várias faixas de bytes numa única requisição. O servidor responde com multipart/byteranges — cada parte tem seu próprio Content-Type e Content-Range. Na prática, multi-faixa é raramente usado: clientes emitem requisições paralelas de faixa única em vez disso (mais simples, mais amigável a cache, mais fácil de recuperar de erros). Alguns servidores limitam o número de faixas ou unem as sobrepostas. Evite depender de multi-faixa em caminhos críticos.

http
# Request multiple ranges in one request
GET /file.bin HTTP/1.1
Range: bytes=0-99,200-299,400-499

# Server responds with multipart/byteranges
HTTP/1.1 206 Partial Content
Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES

--THIS_STRING_SEPARATES
Content-Type: application/octet-stream
Content-Range: bytes 0-99/1024

<100 bytes>
--THIS_STRING_SEPARATES
Content-Type: application/octet-stream
Content-Range: bytes 200-299/1024

<100 bytes>
--THIS_STRING_SEPARATES
Content-Type: application/octet-stream
Content-Range: bytes 400-499/1024

<100 bytes>
--THIS_STRING_SEPARATES--

# Most clients use single-range; multi-range is rare in practice.

Casos de uso de Range

Requisições Range alimentam seeking de vídeo (saltar a um timestamp), downloads retomáveis (continuar após uma pausa), downloads paralelos (gerenciadores dividem arquivos em chunks), pré-visualização de páginas de PDF e leitura de metadados armazenados no fim de arquivos (tags ID3). Para esses casos, o servidor deve suportar faixas e anunciá-lo via Accept-Ranges: bytes. Sem suporte a faixas, seeking de vídeo degrada para download completo, e downloads retomáveis são impossíveis.

http
# 1. Video seeking (HTML5 <video>)
# Browser sends Range when user jumps to a timestamp
GET /video.mp4 HTTP/1.1
Range: bytes=5242880-    # seek to ~5MB offset

# 2. Resumable downloads
# Pause at 50%, resume later
GET /bigfile.zip HTTP/1.1
Range: bytes=524288000-  # continue from 500MB

# 3. Parallel downloads (download managers)
# Split file into N chunks, fetch concurrently
GET /bigfile.zip HTTP/1.1
Range: bytes=0-10485759      # chunk 1 (first 10MB)
# (parallel connection)
GET /bigfile.zip HTTP/1.1
Range: bytes=10485760-20971519  # chunk 2

# 4. PDF preview (load only visible pages)
GET /doc.pdf HTTP/1.1
Range: bytes=102400-204800   # specific page region

# 5. Streaming audio with metadata at the end
# Fetch ID3 tag without downloading the whole file
18

Gerenciamento de sessão

Sessões baseadas em cookie

Sessões baseadas em cookie armazenam uma sessão no servidor (memória, Redis ou DB), indexada por um ID de sessão aleatório. O cookie guarda apenas o ID. Prós: revogável (apague a sessão), cookie pequeno, maduro. Contras: stateful (o servidor precisa armazenar sessões), escalonamento horizontal exige armazenamento de sessão compartilhado (Redis), vulnerável a CSRF (mitigue com SameSite). Melhor para apps web tradicionais com páginas renderizadas no servidor.

http
# 1. User logs in
POST /login HTTP/1.1
Host: example.com
Content-Type: application/json

{"username": "alice", "password": "secret"}

# 2. Server validates, creates session, stores in DB/Redis,
#    returns session ID in a cookie
HTTP/1.1 200 OK
Set-Cookie: session=abc123; HttpOnly; Secure; SameSite=Lax

# 3. Subsequent requests carry the cookie
GET /dashboard HTTP/1.1
Cookie: session=abc123

# 4. Server looks up session ID, finds user, serves request
# 5. Logout: delete session server-side, expire cookie
POST /logout HTTP/1.1
Cookie: session=abc123

HTTP/1.1 200 OK
Set-Cookie: session=; Max-Age=0; Path=/

Sessões baseadas em token (JWT)

Sessões baseadas em token (normalmente JWT) armazenam o estado da sessão DENTRO do token. O servidor valida a assinatura sem consultar o DB — stateless. Prós: escalável (sem armazenamento de sessão), funciona entre serviços, amigável a mobile. Contras: não revogável até expirar (mitigue com access tokens curtos + refresh tokens no servidor), maior que um ID de sessão, vulnerável a XSS se armazenado em localStorage. Melhor para APIs e SPAs.

http
# 1. Login returns a JWT (no server-side state)
POST /login HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{"token": "eyJhbGciOiJIUzI1NiJ9..."}

# 2. Client stores token (memory, sessionStorage)
# 3. Each request includes the token in a header
GET /api/profile HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

# 4. Server validates signature + claims, no DB lookup needed
# 5. Logout: client discards token (no server-side invalidation
#    until exp - this is the stateless tradeoff)

# Refresh token flow:
# - Short-lived access token (5-15 min)
# - Long-lived refresh token (days), stored server-side, revocable
# - When access token expires, exchange refresh token for new one

Sessão em headers

Sessões via headers (Authorization, X-API-Key) são stateless e funcionam para qualquer cliente (navegadores, mobile, CLI, servidor a servidor). O fluxo de refresh-token lida com expiração: access tokens de curta duração limitam o raio de dano de um token roubado, enquanto o refresh token (armazenado com segurança, idealmente num cookie HttpOnly) permite ao cliente obter novos access tokens sem reautenticar. Detecte refresh tokens roubados via rotação.

http
# Bearer token in Authorization header
GET /api/data HTTP/1.1
Authorization: Bearer eyJhbGc...

# Custom header (e.g., API gateway)
GET /api/data HTTP/1.1
X-API-Key: abc123def456

# Basic auth (per-request credentials)
GET /api/data HTTP/1.1
Authorization: Basic dXNlcjpwYXNz

# Bearer + refresh flow:
# 1. Access token expires -> API returns 401
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

# 2. Client uses refresh token to get a new access token
POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=GmR...

# 3. New access token returned
{"access_token": "...", "expires_in": 900}

Expiração e sessão deslizante

Políticas de expiração de sessão: absoluta (tempo de vida fixo desde o login), deslizante (reinicia com atividade) ou combinada (o que vier primeiro). Combinada é a mais segura — limita o comprimento total da sessão enquanto permite um tempo ocioso razoável. Cookies usam Max-Age; sessões no servidor têm um TTL separado. JWTs não deslizam — a claim exp é fixa na emissão. Para 'estender' um JWT, emita um novo (fluxo de refresh-token) em vez de mutar o antigo.

http
# Absolute expiration: session dies after fixed time from login
# e.g., 8 hours after login, regardless of activity
session.expires_at = session.created_at + 8h

# Sliding/Idle expiration: resets on each activity
# e.g., session dies after 30 min of inactivity
session.expires_at = NOW() + 30min   # updated on each request

# Combined (most secure):
# - Absolute cap (e.g., 24h max from login)
# - Idle timeout (e.g., 30min inactivity)
# Whichever comes first.

# Set-Cookie with Max-Age sets cookie lifetime,
# but server-side session may expire earlier (DB cleanup).
Set-Cookie: session=abc; Max-Age=1800  # 30 min

# JWT exp claim (absolute):
# {"exp": 1516242622}  # hardcoded, can't slide

Proteção CSRF

Ataques CSRF exploram o fato de que navegadores enviam cookies automaticamente. Cookies SameSite (Lax por padrão nos navegadores modernos) bloqueiam a maioria dos CSRF ao recusar enviar cookies em POSTs cross-site. O padrão de token CSRF adiciona um token gerado pelo servidor aos formulários e o valida no envio — atacantes não conseguem ler o token por causa da SOP. Defesas de double-submit e header personalizado adicionam defesa em profundidade. APIs usando Bearer tokens (sem cookies) são imunes a CSRF por natureza.

http
# CSRF (Cross-Site Request Forgery): attacker tricks the user's
# browser into sending a state-changing request using their cookies.

# Defense 1: SameSite cookies (modern default)
Set-Cookie: session=abc; SameSite=Lax   # blocks most CSRF
Set-Cookie: session=abc; SameSite=Strict # blocks all cross-site

# Defense 2: CSRF token (synchronizer pattern)
# Server embeds a random token in the form
<form action="/transfer" method="POST">
  <input type="hidden" name="csrf" value="randomtoken123">
  ...
</form>
# Server validates the token on POST

# Defense 3: Double-submit cookie
Set-Cookie: csrf=xyz
# JS reads cookie, includes value in a custom header
X-CSRF-Token: xyz
# (custom headers can't be sent cross-site without preflight)

# Defense 4: Require custom header on state-changing requests
# (browsers block cross-site custom headers without CORS preflight)
19

WebSocket

Upgrade de WebSocket

WebSocket começa como uma requisição HTTP com o header Upgrade. Se o servidor concordar, retorna 101 Switching Protocols. Depois disso, a mesma conexão TCP fala o protocolo binário WebSocket — full-duplex, baixo overhead, sem overhead HTTP por mensagem. O valor Sec-WebSocket-Accept (SHA-1 da chave do cliente mais um GUID fixo) prova que o servidor fez o upgrade intencionalmente. Origin permite que o servidor autorize a fonte do upgrade.

http
# Client initiates HTTP upgrade
GET /ws HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://example.com

# Server accepts upgrade
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

# After 101, the TCP connection is "upgraded" - HTTP is done.
# Both sides send WebSocket frames (binary protocol).

# Sec-WebSocket-Accept = base64(SHA1(key + magic GUID))
# Server must compute this to prove it understood the upgrade.

Handshake de WebSocket (cliente JS)

A API WebSocket do navegador é orientada a eventos: onopen dispara após o upgrade ter sucesso, onmessage a cada frame de entrada, onclose ao desconectar, onerror em falhas. Envie strings ou binário (ArrayBuffer, Blob). Feche com um código (1000 = normal) e um motivo. A conexão é full-duplex — ambos os lados podem enviar a qualquer momento. WSS (WebSocket Secure) usa TLS, equivalente a HTTPS.

http
# Browser client
const ws = new WebSocket('wss://example.com/ws');

ws.onopen = () => {
  console.log('connected');
  ws.send('Hello Server');
};

ws.onmessage = (event) => {
  console.log('received:', event.data);
};

ws.onclose = (event) => {
  console.log('closed:', event.code, event.reason);
};

ws.onerror = (error) => {
  console.error('error:', error);
};

# Send binary
ws.send(new ArrayBuffer(8));

# Close
ws.close(1000, 'normal closure');

Frames de WebSocket

Frames de WebSocket são binários: um bit FIN (fim de mensagem), opcode (text/binary/close/ping/pong), bit de máscara (frames do cliente devem ser mascarados para prevenir cache poisoning por intermediários), comprimento do payload e dados. Códigos de fechamento transmitem por que a conexão terminou — 1000 é normal, 1006 é anormal (sem frame de fechamento, geralmente queda de rede). Frames de ping/pong mantêm a conexão viva e detectam pares mortos. Frames podem ser fragmentados em múltiplos frames.

http
# After the handshake, communication is via binary frames:
# - FIN bit (1 = final fragment of a message)
# - Opcode (4 bits): 0x1 text, 0x2 binary, 0x8 close,
#                    0x9 ping, 0xA pong
# - Mask bit (client->server frames are masked)
# - Payload length (7, 7+16, or 7+64 bits)
# - Masking key (4 bytes, client->server only)
# - Payload data

# Close codes:
# 1000  Normal closure
# 1001  Endpoint going away
# 1006  Abnormal closure (no close frame)
# 1008  Policy violation
# 1011  Internal server error
# 4000-4999  Application-defined

# Ping/Pong: keep-alive and liveness check
# Server: ping -> Client: pong (within timeout)

# Frames can be fragmented (FIN=0) and reassembled.

WebSocket vs HTTP

WebSocket é full-duplex e bidirecional, ideal para apps em tempo real (chat, jogos, dashboards ao vivo, edição colaborativa). HTTP é requisição-resposta — o cliente pergunta, o servidor responde. Para atualizações unidirecionais servidor-cliente, SSE é mais simples (baseado em HTTP, reconecta automaticamente, se dá bem com proxies). Para CRUD stateless, HTTP/REST é o certo. WebSocket tem o menor overhead por mensagem, mas o maior custo de configuração (upgrade, framing).

http
# HTTP: request-response, half-duplex (client initiates)
# WebSocket: full-duplex, either side can send anytime

# Use HTTP when:
# - Client asks, server answers (CRUD APIs)
# - Stateless, cacheable resources
# - Occasional data fetches

# Use WebSocket when:
# - Real-time updates (chat, live sports, dashboards)
# - Bidirectional streaming (collaborative editing, gaming)
# - High-frequency, low-latency messaging
# - Server pushes events without client polling

# Alternatives:
# - SSE (Server-Sent Events): one-way server->client over HTTP
# - HTTP/2 streaming: server can push via DATA frames
# - Long polling: HTTP hack (client polls, server holds open)

# WebSocket has lower per-message overhead than HTTP.

Casos de uso de WebSocket

WebSocket brilha em apps bidirecionais em tempo real: chat, dashboards ao vivo, jogos multijogador, edição colaborativa, notificações e sinalização WebRTC. O desafio é escalar: um cliente conecta a um servidor específico, então transmitir para os clientes precisa de um backend de pub/sub (Redis, Kafka) para espalhar entre instâncias. Use sessões sticky no balanceador, ou desenhe servidores stateless que roteiam mensagens via a camada de pub/sub.

http
# 1. Chat application
# Client sends: {"type": "message", "text": "hi"}
# Server broadcasts to all connected clients

# 2. Live dashboard (stock prices, sports scores)
# Server pushes updates every second
# Client just listens

# 3. Multiplayer game
# Low-latency bidirectional: position, actions, events

# 4. Collaborative editing (Google Docs style)
# Operational Transform / CRDT messages both ways

# 5. Live notifications
# Server pushes: "you have a new message"

# 6. Voice/video signaling (WebRTC)
# WS carries SDP offers/answers before media flows over UDP

# Scaling WebSockets: sticky sessions or a pub/sub backend
# (Redis Pub/Sub, Kafka) so any server can reach any client.
20

Design de API REST

Nomenclatura de recursos

Recursos REST são substantivos (no plural: /users, não /user), com verbos HTTP expressando a ação. Não ponha verbos nas URLs (/createUser está errado — POST /users está certo). Sub-recursos expressam relacionamentos (/users/42/orders). Query parameters tratam filtragem, ordenação, paginação — nunca as asse no path. Use kebab-case para segmentos de path de múltiplas palavras (/password-resets, não /passwordResets). Consistência é a regra mais importante.

http
# Resources are nouns, pluralized
GET /api/users            # list users
POST /api/users           # create user
GET /api/users/42         # get user 42
PUT /api/users/42         # replace user 42
PATCH /api/users/42       # update user 42
DELETE /api/users/42      # delete user 42

# Sub-resources for relationships
GET /api/users/42/orders              # user 42's orders
GET /api/users/42/orders/1001         # specific order

# Use query params for filtering/sorting/pagination
GET /api/users?role=admin&sort=-created_at&page=2&limit=20

# Bad (verbs in URL):
POST /api/createUser     # should be POST /api/users
GET /api/getUser/42      # should be GET /api/users/42

# Good: nouns + HTTP methods express the action.

Verbos HTTP em REST

O mapeamento CRUD padrão do REST: POST=criar, GET=ler, PUT=substituir, PATCH=atualizar, DELETE=excluir. GET/HEAD/OPTIONS são seguros (sem efeitos colaterais). PUT e DELETE são idempotentes. POST não é (repetir cria duplicatas). Para ações que não se encaixam em CRUD (lock, archive, send-email), use um sub-recurso com POST: /users/42/lock. Essa 'válvula de escape RPC' é pragmática — REST puro não modela toda operação de forma limpa.

http
# Standard CRUD mapping:
POST    /users         # Create (server assigns ID)
GET     /users         # List (with filtering/pagination)
GET     /users/:id     # Read one
PUT     /users/:id     # Replace (full update)
PATCH   /users/:id     # Update (partial)
DELETE  /users/:id     # Delete

# Safe (no side effects): GET, HEAD, OPTIONS
# Idempotent (repeatable): GET, HEAD, OPTIONS, PUT, DELETE
# Neither: POST (creates new resource each time)
# PATCH: idempotency depends on the patch format

# Custom "actions" on a resource (RPC-style escape hatch):
POST /users/42/lock      # lock the user (not pure REST)
POST /users/42/unlock
POST /users/42:lock      # Google AIP style
POST /users/42/actions/lock  # explicit escape hatch

Códigos de status em REST

Use códigos de status semanticamente. 200 é sucesso genérico; 201 indica criação (com Location); 204 significa sucesso sem corpo. 400 é entrada malformada; 422 (WebDAV) é bem formada, mas semanticamente inválida (validação). 401 vs 403 é o par mais confundido: 401 = 'quem é você?', 403 = 'sei quem você é, mas não pode fazer isso'. 5xx significa que o servidor errou — clientes podem tentar de novo com backoff. Seja consistente na sua API.

http
# Success (2xx)
200 OK              # generic success, returns data
201 Created         # POST/PUT created a resource (Location header)
202 Accepted        # async job queued (return job URL)
204 No Content      # success, no body (DELETE, PUT)

# Client errors (4xx)
400 Bad Request     # malformed input, validation failure
401 Unauthorized    # not authenticated (needs login)
403 Forbidden       # authenticated but lacks permission
404 Not Found       # resource doesn't exist
409 Conflict        # version conflict, duplicate
422 Unprocessable   # semantic error (well-formed but invalid)
429 Too Many Requests  # rate limited (Retry-After)

# Server errors (5xx)
500 Internal Server Error  # unexpected failure
503 Service Unavailable    # maintenance, overload

# Idempotency: 204 for DELETE/PUT is conventional.
# 201 vs 200 for POST: 201 if a resource was created.

Paginação

Paginação por página (offset/limit) é simples, mas ineficiente em datasets grandes (OFFSET varre linhas passadas) e instável (inserções novas deslocam linhas). Paginação por cursor usa um token opaco apontando ao último item — estável sob inserções concorrentes e rápida (busca indexada na coluna do cursor). Use cursor para scrolls infinitos e feeds grandes; use por página para UIs de admin que precisam de 'ir à página N'. O header Link (RFC 5988) é uma forma HATEOAS de expor URLs de paginação.

http
# Page-based (offset/limit)
GET /api/users?page=2&limit=20
# Response:
{
  "data": [...],
  "page": 2,
  "limit": 20,
  "total": 1000,
  "total_pages": 50
}

# Cursor-based (token, better for large/realtime datasets)
GET /api/users?cursor=abc123&limit=20
# Response:
{
  "data": [...],
  "next_cursor": "def456",
  "has_more": true
}

# Link header (RFC 5988):
Link: <https://api.example.com/users?page=3>; rel="next",
      <https://api.example.com/users?page=50>; rel="last"

# Pros of cursor: stable under inserts/deletes,
# faster on large datasets (no OFFSET scan).
# Cons: can't jump to arbitrary page.

Versionamento de API

Versionamento de API impede que mudanças que quebram compatibilidade prejudiquem clientes existentes. Versionamento por URI (/v1/, /v2/) é a abordagem mais comum e explícita — fácil de depurar, rotear e cachear. Versionamento por header mantém as URLs limpas, mas é mais difícil de testar num navegador. Ao descontinuar, use os headers Sunset e Deprecation (RFC 8594) para anunciar a data de fim de vida, dê tempo amplo aos clientes (6-24 meses) e documente o caminho de migração. Mudanças sem quebra (adicionar campos opcionais) não precisam de bump de versão.

http
# 1. URI versioning (most common, explicit)
GET /api/v1/users
GET /api/v2/users

# 2. Header versioning (cleaner URLs)
GET /api/users
Accept: application/vnd.example.v2+json

# 3. Custom header
X-API-Version: 2

# 4. Query parameter
GET /api/users?version=2

# Deprecation flow:
# - Mark old version as deprecated (Sunset header)
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Deprecation: true
# - Document migration guide
# - Maintain old version for a transition period (6-24 months)
# - Notify clients via email, response headers, logs
# - Eventually shut down the old version

# Breaking changes require a new major version.
# Non-breaking changes (adding fields) don't.

Boas práticas REST

Boas práticas REST: substantivos no plural, funções expressam ações, códigos de status semânticos, paginação por padrão, filtragem via query strings, formato de erro consistente (RFC 7807 problem+json é o padrão) e links de hypermedia para descobribilidade (HATEOAS). Para endpoints POST que não são naturalmente idempotentes (pagamentos, criação de pedidos), aceite um header Idempotency-Key para que clientes possam tentar de novo com segurança sem duplicar efeitos — o servidor armazena a resposta indexada pelo UUID e a reproduz nas retentativas.

http
# 1. Use plural nouns: /users not /user
# 2. HTTP methods express actions (no verbs in URLs)
# 3. Status codes are semantic (201 for create, 404 for missing)
# 4. Pagination on list endpoints (default limit, max cap)
# 5. Filtering via query params: ?role=admin&active=true
# 6. Consistent error format (RFC 7807 problem+json):
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Email is required",
  "instance": "/api/users",
  "errors": [{"field": "email", "message": "required"}]
}

# 7. Hypermedia (HATEOAS) links in responses (optional):
{"data": {...}, "_links": {"self": "/users/42", "orders": "/users/42/orders"}}
# 8. Idempotency keys for safe POST retries (Stripe pattern)
Idempotency-Key: client-generated-uuid

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.