Prévia Markdown
Guia de Referência: HTTP para IA — Referência MDN
Visualização renderizada do arquivo tecnologias/http-mdn.md. O conteúdo abaixo é o mesmo arquivo destinado a orientar a IA.
Guia de Referência: HTTP para IA — Referência MDN
Guia de semântica HTTP para que a IA desenhe comunicação Web com métodos, códigos de status, headers, caching e segurança corretos.
1. Contrato de execução para a IA
- Trate este arquivo como referência de decisão e implementação, não como licença para aplicar toda tecnologia disponível.
- Antes de codificar, declare o ambiente (browser, Node.js, worker, servidor, PWA etc.), os requisitos e as restrições de compatibilidade.
- Prefira a solução nativa e simples quando ela atende aos requisitos com boa acessibilidade, segurança e manutenção.
- Consulte compatibilidade antes de usar APIs experimentais ou de disponibilidade limitada.
- Não misture responsabilidades: estrutura/semântica em HTML, apresentação em CSS, comportamento em JavaScript e capacidades do navegador em Web APIs.
- Considere segurança, privacidade, performance e acessibilidade desde o design, não como correções finais.
2. Modelo
Request/Response
- Conceito: Mensagens entre cliente e servidor em protocolo de aplicação.
- Regra para IA: Defina método, URL, headers e body pelo contrato; resposta deve comunicar resultado por status/headers/body.
Recursos e URLs
- Conceito: Recursos identificados por URI/URL.
- Regra para IA: Modele URLs estáveis, legíveis quando útil e sem vazar segredos.
3. Métodos
GET/HEAD
- Conceito: Leitura/metadata; devem ser safe e idempotentes.
- Regra para IA: Não altere estado do servidor em GET.
POST
- Conceito: Criação/comando/processamento não necessariamente idempotente.
- Regra para IA: Use quando semântica não cabe em PUT/PATCH ou para criar sob uma coleção.
PUT
- Conceito: Substituição idempotente do recurso identificado.
- Regra para IA: Use quando cliente conhece URI e envia representação completa conforme contrato.
PATCH
- Conceito: Alteração parcial.
- Regra para IA: Defina formato de patch e validação de concorrência quando necessário.
DELETE
- Conceito: Remoção idempotente em intenção.
- Regra para IA: Retorne status coerente mesmo se operação física for assíncrona.
OPTIONS
- Conceito: Capacidades/preflight.
- Regra para IA: Entenda seu papel em CORS e discovery.
4. Status
2xx
- Conceito: Sucesso: 200, 201, 202, 204 etc.
- Regra para IA: Use 201 com Location quando recurso é criado, 202 para aceitação assíncrona, 204 sem body.
3xx
- Conceito: Redirecionamento e cache.
- Regra para IA: Diferencie redirecionamentos permanentes/temporários e preservação de método.
4xx
- Conceito: Erro de cliente: 400, 401, 403, 404, 409, 422, 429 etc.
- Regra para IA: Escolha status pela semântica e forneça erro estruturado sem detalhes sensíveis.
5xx
- Conceito: Falha do servidor/upstream.
- Regra para IA: Não transforme erro interno em 200; registre correlação e mensagem segura ao cliente.
5. Headers e representação
Content negotiation
- Conceito: Content-Type, Accept e variantes.
- Regra para IA: Declare tipo correto e negocie formatos quando necessário.
Caching
- Conceito: Cache-Control, validators, ETag/If-None-Match, Last-Modified.
- Regra para IA: Defina cache conscientemente; não marque dados privados como public por engano.
Cookies
- Conceito: Secure, HttpOnly, SameSite, domain/path e expiração.
- Regra para IA: Aplique menor escopo; sessões sensíveis devem usar atributos seguros.
CORS
- Conceito: Access-Control-* e preflight.
- Regra para IA: Permita somente origins/métodos/headers necessários; nunca use
*com credenciais.
Autenticação
- Conceito: Authorization e desafios apropriados.
- Regra para IA: Não coloque token em URL; transporte sempre sobre HTTPS.
6. Transporte e evolução
HTTPS
- Conceito: HTTP protegido por TLS.
- Regra para IA: Use HTTPS em produção e trate conteúdo misto como falha.
HTTP/2 e HTTP/3
- Conceito: Evoluções de transporte mantendo semântica HTTP.
- Regra para IA: Não mude contrato de aplicação apenas por versão de transporte; otimize depois de medir.
Checklist de aceite
- A tecnologia escolhida resolve um requisito real e foi aplicada no ambiente correto.
- Semântica, acessibilidade e estados de teclado/foco foram revisados.
- Entradas externas são tratadas como não confiáveis e saídas são renderizadas com segurança.
- Erros, estados vazios, carregamento, offline/rede e cancelamento foram considerados quando aplicável.
- Compatibilidade e fallback foram avaliados para recursos não Baseline/amplamente suportados.
- O código não duplica APIs nativas ou responsabilidades de outra camada.
- Performance foi medida quando a decisão tem impacto relevante.
Prompt-base para IA
Use o guia "HTTP para IA — Referência MDN" anexado como contrato técnico.
Analise meu requisito e escolha somente os conceitos necessários.
Diga quais partes do guia serão aplicadas e por quê.
Implemente com semântica, acessibilidade, segurança e compatibilidade.
Não invente APIs.
Ao final, revise a solução pelo checklist do guia.
Contexto: [DESCREVA o sistema, stack/versões, ambiente e estado atual]
Objetivo: [DESCREVA o resultado observável esperado]
Restrições: [DESCREVA o que não pode mudar e os limites técnicos]
Como preencher os campos
- Contexto: descreva sistema, stack/versões, arquitetura ou ambiente, estado atual e onde a mudança acontece.
- Objetivo: descreva o resultado observável esperado — o que o usuário ou o sistema deve conseguir fazer ao final.
- Restrições: descreva o que não pode mudar e os limites de compatibilidade, segurança, acessibilidade, performance, dependências e escopo.
Exemplo preenchido
Contexto: Frontend consulta uma API REST autenticada e precisa atualizar parcialmente um cadastro já existente.
Objetivo: Definir método, status, headers, cache e tratamento de erros para a atualização parcial.
Restrições: HTTPS obrigatório; não colocar token na URL; preservar idempotência quando aplicável; respostas de erro devem ser previsíveis.
Fontes primárias
- MDN HTTP: https://developer.mozilla.org/pt-BR/docs/Web/HTTP