Headers API | Design de API's | CSharp

• Headers API | Design de API's | CSharp

---

User-Agent

• O agente do usuário é um conjunto de strings enviadas por aplicativos da web ou clientes de API ao fazer chamadas HTTP para os servidores web de backend. Geralmente, especificamos no formato: User-Agent: Product/ProductVersion <comments>

O valor do cabeçalho contém três informações distintas:

• Produto: Informações sobre o produto que faz as chamadas HTTP
• Versão do produto: A versão do produto
• Comentários: Nenhum ou mais comentários que forneçam mais detalhes sobre o produto

Exemplo de uso: User-Agent: CodeMazeDesktopApp/1.1

Além disso, podemos usar User-Agent:

• Para verificar e limitar o acesso às nossas APIs apenas a determinados produtos ou navegadores
• Para verificar e personalizar a experiência do usuário de nossos aplicativos da web com base no tipo de dispositivo que faz a chamada HTTP
• Para analisar os comportamentos de engajamento do usuário com base no dispositivo usado para acessar nossos aplicativos da web ou APIs

Documentação sobre Headers

1) Visão geral: request, response e corpo

Uma transação HTTP tem duas partes:

• Headers: metadados (pequenos, porém críticos).
• Body: conteúdo real (HTML, JSON, imagem, etc.).

O cliente faz uma request; o servidor devolve uma response.

---

2) Códigos de Status HTTP (resumo rápido) | Status HTTP

Indicam o resultado da request:

Classe	Status Code	Nome	Explicação
2xx	200	OK	A requisição foi processada com sucesso e o recurso está sendo retornado. (pode retornar o dado caso já esteja criado ou retorne 409)
	201	Created	O recurso foi criado com sucesso. Normalmente usado após POST.
	202	Accepted	A requisição foi aceita para processamento, mas ainda não concluída (processamento assíncrono).
	204	No Content	A requisição foi bem-sucedida, mas não há conteúdo para retornar.
3xx	301	Moved Permanently	O recurso foi movido permanentemente para outra URL.
	302	Found	Redirecionamento temporário para outra URL.
	307	Temporary Redirect	Redirecionamento temporário mantendo o mesmo método HTTP.
	308	Permanent Redirect	Redirecionamento permanente mantendo o método HTTP.
4xx	400	Bad Request	A requisição é inválida ou malformada.
	401	Unauthorized	Autenticação necessária ou inválida.
	403	Forbidden	O cliente está autenticado, mas não tem permissão.
	404	Not Found	O recurso solicitado não foi encontrado.
	409	Conflict	Conflito com o estado atual do recurso (ex.: tentativa de criar algo que já existe).
	422	Unprocessable Entity	A requisição é semanticamente inválida (validação falhou).
5xx	500	Internal Server Error	Erro inesperado no servidor.
	502	Bad Gateway	Resposta inválida de um servidor upstream.
	503	Service Unavailable	Serviço temporariamente indisponível.
	504	Gateway Timeout	Timeout ao aguardar resposta de outro servidor.

• OBS: Abaixo contém alguns detalhes importantes do 3xx

Detalhes de cache da categoria 3xx

Status	Nome	Cacheável por padrão?	Precisa de Cache-Control para cache?	Observações
301	Moved Permanently	✅ Sim	❌ Não	Redirecionamento permanente. Navegadores costumam cachear automaticamente.
302	Found (Temporary)	❌ Não	✅ Sim	Só é cacheado se houver Cache-Control ou Expires.
303	See Other	❌ Não	✅ Sim	Mesmo comportamento do 302.
307	Temporary Redirect	❌ Não	✅ Sim	Redirecionamento temporário mantendo o método HTTP.
308	Permanent Redirect	✅ Sim	❌ Não	Permanente como o 301, mantém o método HTTP.

Cabeçalho	Efeito no Cache
Cache-Control: no-store	❌ Nunca armazena
Cache-Control: no-cache	⚠️ Pode armazenar, mas precisa revalidar
Cache-Control: max-age=N	⏳ Define tempo de cache
Expires	📅 Define data de expiração
Location	🔁 Define a URL de redirecionamento

---

3) Headers Gerais (presentes em requests e responses)

3.1 Cache-Control

Controla o comportamento de cache em navegadores, proxies e CDNs.

Exemplos:

• Cache-Control: max-age=3600, public → pode cachear por 3600s em todas as camadas.
• Cache-Control: no-store → não cachear em lugar nenhum.
• Cache-Control: no-cache → pode armazenar, mas deve revalidar antes de usar.

Impacto: configuração incorreta pode servir dados obsoletos ou vazar dados privados.

---

3.2 Date

Indica quando a response foi enviada; usado para calcular frescor de cache e depurar relógio.

Ex.: Date: Sun, 22 Aug 2025 14:00:00 GMT

---

3.3 Via

Adicionado por proxies; mostra o caminho da mensagem.

Ex.: Via: 1.1 proxy1.example.com, 1.1 proxy2.example.com

---

4) Request Headers (enviados pelo cliente)

4.1 Host

Host/porta do servidor alvo (suporta virtual hosting).

Ex.: Host: blog.example.com

Possível erro sem header: 400 ou site padrão incorreto.

---

4.2 User-Agent

Identifica navegador/SO; útil para analytics, compatibilidade e otimização.

Ex.: User-Agent: Mozilla/5.0 (...) Chrome/114.0...

---

4.3 Accept

Negociação de conteúdo: formatos preferidos (ex.: JSON, HTML).

Ex.: Accept: application/json

---

4.4 Accept-Language

Preferências de idioma humano.

Ex.: Accept-Language: en-US, de;q=0.9

---

4.5 Accept-Encoding

Algoritmos de compressão suportados (gzip, br, etc.).

Ex.: Accept-Encoding: gzip, deflate, br

---

4.6 Cookie

Cookies do cliente (sessão, preferências, etc.).

Ex.: Cookie: session_id=abc567; theme=dark

---

4.7 Referer (sic)

URL de origem que levou à página atual (útil em analytics).

Ex.: Referer: https://example.com/page1

---

4.8 Authorization

Credenciais/Token para autenticar.

Ex.: Authorization: Bearer <jwt>

---

4.9 Range

Download parcial por intervalos (streaming/recomeço de download).

Ex.: Range: bytes=0-499

---

4.10 If-Modified-Since

Request condicional por data.

Ex.: If-Modified-Since: Tue, 11 Jun 2024 10:00:00 GMT

---

4.11 If-None-Match

Request condicional por ETag (versão precisa do recurso).

Ex.: If-None-Match: "abc123"

---

4.12 X-Forwarded-For

Inserido por proxies; indica IP original do cliente.

Ex.: X-Forwarded-For: 203.0.113.21

---

4.13 X-Forwarded-Proto

Protocolo original (HTTP/HTTPS) antes do proxy.

Ex.: X-Forwarded-Proto: https

---

4.14 X-Forwarded-Port

Porta original (80/443 etc.) antes do proxy.

Ex.: X-Forwarded-Port: 443

---

5) Response Headers (enviados pelo servidor)

5.1 Location

Usado em redirecionamentos.

Ex.: Location: https://example.com/welcome

---

5.2 Set-Cookie

Armazena cookies no cliente (sessão, preferências, segurança).

Ex.: Set-Cookie: session_id=abc123; Path=/; HttpOnly

---

5.3 Access-Control-Allow-Origin (CORS)

Permite leitura cross-origin por navegadores.

Ex.: Access-Control-Allow-Origin: https://ecommerce-store.com

---

5.4 Age

Adicionado por caches; idade (em segundos) do objeto cacheado.

Ex.: Age: 120

---

5.5 Vary

Define quais request headers variam a resposta (chave de cache).

Ex.: Vary: User-Agent

---

5.6 Accept-Ranges

Indica suporte a requisições parciais.

Ex.: Accept-Ranges: bytes

---

5.7 Content-Range

Indica qual parte foi enviada numa resposta parcial.

Ex.: Content-Range: bytes 0-499/1234

---

5.8 Content-Security-Policy (CSP)

Lista de fontes permitidas para scripts/estilos/imagens (mitiga XSS).

Ex.: Content-Security-Policy: default-src 'self'; script-src 'self'

---

5.9 Strict-Transport-Security (HSTS)

Obriga uso de HTTPS por um período.

Ex.: Strict-Transport-Security: max-age=31536000; includeSubDomains

---

6) Payload Headers (descrevem o corpo)

6.1 Content-Type

Formato do body (MIME type).

Ex.: Content-Type: application/json

---

6.2 Content-Disposition

Instrui exibir inline ou baixar como arquivo.

Ex.: Content-Disposition: attachment; filename="report.pdf"

---

6.3 Content-Length

Tamanho do corpo em bytes.

Ex.: Content-Length: 348

---

6.4 Content-Encoding

Algoritmo de compressão aplicado ao body.

Ex.: Content-Encoding: gzip

---

6.5 Content-Language

Idioma humano do body.

Ex.: Content-Language: en-US

---

6.6 Last-Modified

Data/hora da última modificação do recurso.

Ex.: Last-Modified: Tue, 11 Jun 2024 10:00:00 GMT

---

6.7 ETag

Identificador único (versão) do recurso; usado com validação condicional.

Ex.: ETag: "abc123"

---

7) Boas práticas essenciais

• Cache com cuidado: defina Cache-Control apropriado (estático vs. dinâmico) e use Vary quando a resposta depender de headers (idioma, UA, compressão).
• Segurança: ative HTTPS e HSTS; adote CSP; proteja cookies com HttpOnly, Secure, SameSite.
• Negociação de conteúdo: respeite Accept, Accept-Language e Accept-Encoding para entregar respostas corretas e mais leves.
• Condicionais: use ETag/Last-Modified com If-None-Match/If-Modified-Since para economizar banda (retornar 304 quando possível).
• Proxies/CDN: confie em X-Forwarded-* ao gerar URLs/registrar IPs; valide Via/Age ao depurar rotas e cache.
• Redirecionamentos: sempre defina Location válido e o status adequado (301/302/307/308).

---

8) Cheatsheet (tabela rápida)

Header	Tipo	Para que serve
Cache-Control	Geral	Regras de cache em todas as camadas
Date	Geral	Hora de envio da response
Via	Geral	Caminho por proxies
Host	Request	Virtual hosting/rotear domínio
User-Agent	Request	Identificar cliente e adaptar conteúdo
Accept	Request	Negociar formato (JSON/HTML/...)
Accept-Language	Request	Preferência de idioma
Accept-Encoding	Request	Compressão suportada
Cookie	Request	Sessão/preferências
Referer	Request	Origem do tráfego
Authorization	Request	Autenticação (Bearer/API Key)
Range	Request	Downloads parciais
If-Modified-Since	Request	Validação condicional por data
If-None-Match	Request	Validação condicional por ETag
X-Forwarded-For/Proto/Port	Request (proxy)	IP/protocolo/porta originais
Location	Response	Redirecionamento
Set-Cookie	Response	Persistir cookie no cliente
Access-Control-Allow-Origin	Response	CORS: liberar leitura cross-origin
Age	Response	Idade do cache
Vary	Response	Chave de variação do cache
Accept-Ranges	Response	Suporte a parciais
Content-Range	Response	Faixa enviada (206)
Content-Security-Policy	Response	Fontes permitidas (mitiga XSS)
Strict-Transport-Security	Response	Força HTTPS
Content-Type	Payload	Tipo de mídia do body
Content-Disposition	Payload	Inline vs. download
Content-Length	Payload	Tamanho do body
Content-Encoding	Payload	Compressão aplicada
Content-Language	Payload	Idioma do body
Last-Modified	Payload	Data da última modificação
ETag	Payload	Versão do recurso

---