Acervo.estudos
Trilhas Enviar material Entrar
mapa · Intermediário

4.1 APIs e o padrão REST

O que é uma API web e o estilo REST: recursos, métodos HTTP, idempotência, códigos de status e como ler e devolver JSON em PHP com php://input e json_encode.

por @julio · rev. 23 set · 6 telas

Um contrato entre programas

O que é uma API web

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
{
  "id": 1,
  "nome": "Ana Souza",
  "email": "ana@ifrs.edu.br"
}

JSON: objetos { }, listas [ ], textos entre aspas duplas, números, true/false/null. No PHP, json_encode gera e json_decode lê.

⚠ A página original atribui a especificação do HTTP ao W3C ("W3C, 2024"). O HTTP é padronizado pela IETF; a semântica atual está na RFC 9110, de junho de 2022.

Recursos, verbos e idempotência

REST e os métodos HTTP

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
MétodoRotaAçãoSucesso típicoIdempotente
GET/users, /users/1ler200sim
POST/userscriar201 + Locationnão
PUT/users/1substituir200 ou 204sim
PATCH/users/1alterar em parte200 ou 204não garantido
DELETE/users/1remover204 (ou 200 com corpo)sim

Idempotente não quer dizer "mesma resposta": o segundo DELETE de /users/1 pode responder 404, mas o estado do servidor é o mesmo.

O número diz o que aconteceu

Códigos de status

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom

Regra prática: erro de formato → 400; formato certo mas regra violada (e-mail inválido, campo vazio) → 422; o problema foi do servidor → 500. Nunca responda 200 com {"erro": …} no corpo.

HTML pronto ou só dados

Formulário tradicional × API

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
<?php
// processa_cadastro.php (versão segura)
declare(strict_types=1);

$nome  = trim($_POST['nome'] ?? '');
$email = filter_var($_POST['email'] ?? '', FILTER_VALIDATE_EMAIL);

if ($nome === '' || $email === false) {
    http_response_code(422);
    echo '<p>Preencha nome e um e-mail válido.</p>';
    exit;
}
// ... INSERT com prepared statement ...
echo '<p>Cadastrado: ', htmlspecialchars($nome), '</p>';

⚠ O processa_cadastro.php da página original faz echo "<p>Nome: $nome</p>" com o valor cru de $_POST. Um nome como <script>…</script> roda no navegador (XSS). Use htmlspecialchars(). Aberto sem POST, o script ainda gera Warning: Undefined array key "nome".

php://input, json_decode, json_encode e roteamento

Recebendo e devolvendo JSON em PHP

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
<?php
// public/index.php (esqueleto)
declare(strict_types=1);

header('Content-Type: application/json; charset=utf-8');
$caminho = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);   // ignora ?page=2
$metodo  = $_SERVER['REQUEST_METHOD'];

if ($caminho === '/users') {
    if ($metodo === 'POST') {
        try {
            $dados = json_decode(file_get_contents('php://input'), true, 512, JSON_THROW_ON_ERROR);
        } catch (JsonException) {
            http_response_code(400);
            echo json_encode(['erro' => 'JSON inválido'], JSON_UNESCAPED_UNICODE);
            exit;
        }
        http_response_code(201);
        echo json_encode(['recebido' => $dados], JSON_UNESCAPED_UNICODE);
        exit;
    }
    header('Allow: POST');
    http_response_code(405);
    echo json_encode(['erro' => 'Método não permitido'], JSON_UNESCAPED_UNICODE);
    exit;
}
http_response_code(404);
echo json_encode(['erro' => 'Rota não encontrada'], JSON_UNESCAPED_UNICODE);

⚠ No roteador da página original, um método não tratado (ex.: PUT) cai no default com 404 "Rota não encontrada"; o certo é 405 com cabeçalho Allow. O POST que cria responde 200 (deveria ser 201) e nenhuma resposta envia Content-Type: application/json. Além disso, sem JSON_UNESCAPED_UNICODE a saída real é "Usuário".

⚠ A página original compara $_SERVER['REQUEST_URI'] === '/users'. O REQUEST_URI inclui a query string: /users?page=2 não casa e vira 404. Use parse_url(…, PHP_URL_PATH), como a aula 4.2 faz.

⚠ O exemplo de fetch() para http://localhost:8000/users só funciona se a página também vier de localhost:8000. De outra origem (arquivo aberto direto, Live Server na porta 5500), o navegador faz uma requisição OPTIONS antes e exige cabeçalhos CORS (Access-Control-Allow-Origin), que o backend mostrado não envia.

Teste antes de seguir

Revisão rápida

clique nos círculos para abrir e fechar ramos · arraste para mover · role para dar zoom
POST é idempotente?

Não. Enviar duas vezes o mesmo POST /users cria dois usuários (ou dá 409 se houver UNIQUE).

A rota /users existe, mas chegou um PATCH que a API não aceita. Qual status?

405 Method Not Allowed, com o cabeçalho Allow listando os métodos aceitos (ex.: Allow: GET, POST).

O cliente mandou JSON válido, mas o e-mail está vazio. 400 ou 422?

422: a sintaxe está certa, o conteúdo é que não passa na validação. 400 fica para JSON malformado.

Por que $_POST vem vazio quando o cliente envia JSON?

O PHP só preenche $_POST para formulários (application/x-www-form-urlencoded ou multipart/form-data). JSON é lido em php://input.

Qual status devolver depois de criar um recurso?

201 Created, de preferência com o cabeçalho Location apontando para o novo recurso (ex.: /users/8).

← Voltar ao curso