# 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 1. [ ] A tecnologia escolhida resolve um requisito real e foi aplicada no ambiente correto. 2. [ ] Semântica, acessibilidade e estados de teclado/foco foram revisados. 3. [ ] Entradas externas são tratadas como não confiáveis e saídas são renderizadas com segurança. 4. [ ] Erros, estados vazios, carregamento, offline/rede e cancelamento foram considerados quando aplicável. 5. [ ] Compatibilidade e fallback foram avaliados para recursos não Baseline/amplamente suportados. 6. [ ] O código não duplica APIs nativas ou responsabilidades de outra camada. 7. [ ] Performance foi medida quando a decisão tem impacto relevante. --- ## Prompt-base para IA ```text 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 ```text 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