Curso HTTP Request (com Postman)

Repositório de apoio para um curso prático de HTTP Requests usando Postman, focado em quem trabalha com integrações. Aqui você vai clonar o projeto, instalar o PHP e subir um servidor local para testar os endpoints no Postman.

Índice

• Cronograma
• Pré-requisitos
• Instalação rápida (scripts)
• Instalar PHP (manual)
• Instalar Git
• Clonar e executar
• Endpoints de exemplo v1
• Como testar no Postman
• Guia de status codes
• Resultado esperado

Cronograma (resumido e eficiente)

Aula 1 — Fundamentos e arquitetura

• Arquitetura cliente-servidor: papéis, responsabilidades e limites.
• O que é HTTP: protocolo, recursos, URI/URL, métodos.
• O “ciclo” request/response e onde as integrações quebram.
• Ferramentas: Postman (coleções, environments) e servidor local em PHP.

Aula 2 — Anatomia da requisição (Request)

• Linha da requisição: método + caminho + versão.
• Headers: Content-Type, Accept, Authorization, User-Agent, Cache-Control.
• Query params vs path params.
• Body: JSON, form-data, x-www-form-urlencoded, raw.
• Boas práticas: validação, encoding, tamanho de payload e versionamento (/v1).

Aula 3 — Anatomia da resposta (Response)

• Status codes na prática: 2xx, 3xx, 4xx, 5xx.
• Headers de resposta: Content-Type, Location, ETag, Cache-Control, Retry-After.
• Resposta consistente: envelope, mensagens, e formatos de erro.
• Debug: como ler uma resposta rapidamente e achar o “ponto de falha”.

Aula 4 — Métodos HTTP e semântica (integrações reais)

• GET, POST, PUT, PATCH, DELETE: quando usar cada um.
• Idempotência, segurança, caching e efeitos colaterais.
• Paginação, filtros, ordenação e versionamento.

Aula 5 — Autenticação e autorização

• Basic, API Key, Bearer/JWT (conceitos e uso no Postman).
• Rotação de credenciais, escopos e boas práticas de segurança.
• Erros comuns: 401 vs 403, expiração, clock skew.

Aula 6 — Postman para produtividade

• Collections e folders.
• Environments e variáveis (globals/collection/environment).
• Pre-request scripts e testes simples (asserts).
• Collection Runner (rodar cenários e regressão rápida).

Aula 7 — Resiliência e detalhes técnicos que fazem diferença

• Timeouts, retries, backoff, rate limiting (429) e circuit breaker (conceito).
• CORS (quando aparece e por quê), proxies e SSL/TLS (visão prática).
• Caching (ETag/If-None-Match) e concorrência.

Aula 8 — Projeto final (hands-on)

• Modelar um mini contrato de API (endpoints + payloads + erros).
• Implementar endpoints simples em PHP para simular uma API.
• Criar coleção Postman completa (cenários ok e cenários de erro).

Conceitos-chave que você vai dominar

Cliente-servidor (mentalidade)

• Cliente “pede”, servidor “responde”. A integração é a combinação de contrato + transporte + dados.
• O contrato é tão importante quanto o código: método, rota, headers, body, status codes e erros.

Requisição sempre “fecha” com uma resposta

No HTTP, toda requisição precisa terminar com algum tipo de resposta válida do ponto de vista do protocolo: sucesso, erro, redirecionamento ou timeout/conexão encerrada.

• O que muda na prática é a estratégia do servidor:
  • “Responder depois de processar”: retorna 200/201 com o resultado pronto.
  • “Responder antes e processar em segundo plano”: retorna 202 Accepted com um identificador, e o cliente consulta o status depois (polling) ou recebe um callback (webhook).
• No cliente, você pode programar de forma bloqueante ou não-bloqueante, mas o modelo HTTP continua sendo request/response.

Pré-requisitos

• Git
• (Opcional) GitHub Desktop (alternativa ao Git no terminal)
• (Opcional) GitHub CLI (gh) para clonar mais rápido
• Postman (Desktop recomendado)
• PHP 8.1+ (CLI)

Instalação rápida (scripts)

Se você quiser automatizar a instalação de Git e PHP, use os scripts desta pasta:

Windows

1. Clique com o botão direito em scripts\windows\install-tools.bat
2. Escolha “Executar como administrador”
3. Esse script instala o Chocolatey (se necessário) e instala git + php

Alternativa via PowerShell (rodando na pasta do projeto):

Start-Process -Verb RunAs -FilePath ".\scripts\windows\install-tools.bat"

Linux

chmod +x scripts/linux/install-tools.sh
./scripts/linux/install-tools.sh

macOS

chmod +x scripts/macos/install-tools.sh
./scripts/macos/install-tools.sh

Instalar PHP (manual)

Windows (instalação manual)

1. Baixe o PHP para Windows (Thread Safe ou Non Thread Safe funcionam para CLI; prefira a versão estável) em: https://windows.php.net/download/
2. Extraia o .zip para um diretório, por exemplo: C:\php
3. Adicione C:\php ao PATH:
   • Painel de Controle → Sistema → Configurações avançadas → Variáveis de ambiente → Path → Adicionar C:\php
   • (Opcional) via CMD (como Administrador):

setx /M PATH "%PATH%;C:\php"

4. (Opcional) Crie php.ini:
   • Copie php.ini-development para php.ini
5. Verifique no PowerShell:

php -v
php -m

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y php php-cli
php -v

Se sua distro não for baseada em Debian, instale pelos pacotes equivalentes (ex.: dnf install php-cli, pacman -S php).

macOS (Homebrew)

brew update
brew install php
php -v

Instalar Git (se necessário)

Windows (opção via winget)

winget install -e --id Git.Git
git --version

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y git
git --version

macOS (Homebrew)

brew install git
git --version

Clonar o repositório e iniciar o servidor PHP (porta 9000)

Clonar via Git (terminal)

git clone https://github.com/felipelm3g/Curso-HTTP-Request.git

Clonar via GitHub CLI (terminal)

gh repo clone felipelm3g/Curso-HTTP-Request

Clonar via GitHub Desktop

• File → Clone Repository → URL
• Cole: https://github.com/felipelm3g/Curso-HTTP-Request
• Escolha a pasta de destino e conclua o clone

Entrar na pasta clonada

cd Curso-HTTP-Request

Iniciar o servidor embutido do PHP na porta 9000

Se os arquivos PHP (por exemplo index.php) estiverem na raiz do projeto:

php -S localhost:9000

Se existir uma pasta pública (ex.: public/) com o arquivo inicial:

php -S localhost:9000 -t public

Conferir no navegador

• http://localhost:9000

Endpoints de exemplo v1

• GET: http://localhost:9000/v1/get.php
• POST: http://localhost:9000/v1/post.php
• PUT: http://localhost:9000/v1/put.php
• PATCH: http://localhost:9000/v1/patch.php
• DELETE: http://localhost:9000/v1/delete.php

Sugestões de corpo (JSON) para testar:

{
  "id": 123,
  "name": "Exemplo",
  "active": true
}

Como testar no Postman (fluxo sugerido)

• Crie uma Collection “Curso HTTP”.
• Crie um Environment “Local” com a variável baseUrl = http://localhost:9000.
• Monte as requests usando {{baseUrl}}/sua-rota.
• Para cada endpoint, teste:
  • Caso de sucesso (2xx)
  • Erros de validação (400/422)
  • Não autenticado (401) e sem permissão (403), quando aplicável
  • Não encontrado (404)
  • Erro inesperado (500) para aprender a identificar sinais no response

Guia rápido de status codes (para integrações)

• 200 OK: sucesso com retorno
• 201 Created: recurso criado (ideal com header Location)
• 204 No Content: sucesso sem body (comum em DELETE)
• 301/302: redirecionamento (muito comum em URL antiga)
• 400 Bad Request: request inválida (formato/param faltando)
• 401 Unauthorized: faltou credencial ou é inválida
• 403 Forbidden: credencial ok, mas sem permissão
• 404 Not Found: rota/recurso não existe
• 409 Conflict: conflito de estado (ex.: duplicidade)
• 422 Unprocessable Entity: validação semântica falhou
• 429 Too Many Requests: rate limit
• 500/502/503: erro no servidor/infra

Resultado esperado do curso

• Ler e montar requests rapidamente (método, rota, headers e body).
• Diagnosticar integração por status code + headers + payload.
• Montar uma coleção Postman reutilizável (com variáveis e testes).
• Entender padrões de API que evitam retrabalho: idempotência, paginação, erros consistentes e resiliência.