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.
O que é uma API web
{
"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.
REST e os métodos HTTP
| Método | Rota | Ação | Sucesso típico | Idempotente |
|---|---|---|---|---|
| GET | /users, /users/1 | ler | 200 | sim |
| POST | /users | criar | 201 + Location | não |
| PUT | /users/1 | substituir | 200 ou 204 | sim |
| PATCH | /users/1 | alterar em parte | 200 ou 204 | não garantido |
| DELETE | /users/1 | remover | 204 (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.
Códigos de status
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.
Formulário tradicional × API
<?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".
Recebendo e devolvendo JSON em PHP
<?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.
Revisão rápida
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).