O que é uma API REST?

Você já se perguntou como um aplicativo de celular consegue consultar informações de um site ou como dois sistemas diferentes conseguem trocar dados pela internet?

Em muitos casos, essa comunicação acontece por meio de uma API REST.

As APIs estão presentes em diversas aplicações que utilizamos diariamente, desde sistemas de pagamento até aplicativos de delivery, redes sociais e plataformas de comércio eletrônico.

Neste artigo, você vai entender o que é uma API REST, como ela funciona e como criar uma API simples utilizando apenas PHP puro, sem precisar instalar frameworks.

O que é uma API?

API é a sigla para Application Programming Interface, ou Interface de Programação de Aplicações.

De forma simples, uma API é um conjunto de regras e recursos que permite a comunicação entre diferentes sistemas.

Imagine um aplicativo de previsão do tempo. Ele precisa mostrar a temperatura de determinada cidade, mas não necessariamente armazena essas informações.

Em vez disso, o aplicativo pode fazer uma requisição para uma API de meteorologia, que retorna os dados solicitados.

O aplicativo recebe essas informações e as apresenta ao usuário.

Assim, a API funciona como uma ponte de comunicação entre sistemas.

O que é uma API REST?

REST significa Representational State Transfer, ou Transferência de Estado Representacional.

É um estilo arquitetural utilizado na construção de sistemas distribuídos, especialmente serviços web.

Uma API REST segue princípios que ajudam a organizar a comunicação entre cliente e servidor.

Entre os principais estão:

• Cliente-servidor: separação entre quem solicita informações e quem as fornece.

• Stateless: cada requisição deve conter as informações necessárias para ser processada, sem depender de um estado de sessão armazenado no servidor.

• Interface uniforme: utilização de convenções consistentes para identificar e manipular recursos.

• Cache: respostas podem indicar se são armazenáveis em cache.

• Sistema em camadas: a comunicação pode passar por intermediários, como proxies e gateways.

Uma API REST normalmente utiliza HTTP para realizar operações sobre recursos identificados por URLs.

É importante lembrar que REST não é uma linguagem de programação nem um framework.

Como funciona uma API REST?

O funcionamento de uma API REST envolve dois elementos principais:

Cliente: é quem realiza a requisição, como um navegador, aplicativo ou outro sistema.

Servidor: é quem recebe a requisição, processa as informações e retorna uma resposta.

Imagine uma API de produtos disponível no endereço:

https://exemplo.com/api/produtos

Quando o cliente realiza uma requisição GET, o servidor pode retornar:

[
  {
    "id": 1,
    "nome": "Notebook",
    "preco": 3500
  },
  {
    "id": 2,
    "nome": "Mouse",
    "preco": 80
  }
]

Essas informações estão no formato JSON, bastante utilizado em APIs.

O que é JSON?

JSON significa JavaScript Object Notation.

É um formato textual utilizado para representar e trocar dados entre aplicações.

Um exemplo:

{
  "id": 1,
  "nome": "João",
  "email": "joao@exemplo.com",
  "ativo": true
}

Apesar do nome, JSON não é exclusivo do JavaScript.

Linguagens como PHP, Python, Java e muitas outras conseguem trabalhar com esse formato.

No PHP, podemos transformar um array em JSON utilizando json_encode():

<?php
$usuario = [
    'id' => 1,
    'nome' => 'João',
    'email' => 'joao@exemplo.com'
];
echo json_encode($usuario);

Também podemos converter JSON em um array PHP utilizando json_decode().

Quais são os principais métodos HTTP?

O protocolo HTTP possui métodos que indicam a operação desejada pelo cliente.

Em APIs REST, alguns métodos são especialmente comuns.

Método	Finalidade	Exemplo
GET	Consultar recursos	Listar produtos
POST	Criar recursos	Cadastrar produto
PUT	Substituir um recurso	Atualizar produto
PATCH	Modificar parcialmente	Alterar preço
DELETE	Excluir recursos	Remover produto

GET - Consultar dados

O método GET é utilizado para solicitar informações.

Exemplo:

GET /api/produtos

A API retorna uma lista de produtos.

Para consultar apenas um produto:

GET /api/produtos/1

POST — Criar dados

O método POST é frequentemente utilizado para criar novos recursos.

POST /api/produtos
Content-Type: application/json

Corpo da requisição:

{
  "nome": "Teclado",
  "preco": 150
}

O servidor processa os dados e pode retornar o recurso criado.

PUT — Atualizar dados

O método PUT é utilizado para criar ou substituir a representação de um recurso no endereço indicado. Em muitos CRUDs, ele é utilizado para substituir um registro existente.

PUT /api/produtos/1
Content-Type: application/json

{
  "nome": "Notebook Gamer",
  "preco": 5000
}

DELETE — Excluir dados

O método DELETE solicita a remoção de um recurso.

DELETE /api/produtos/1

A API pode responder com o status HTTP 204 No Content quando a exclusão for concluída sem retornar conteúdo.

O que são códigos de status HTTP?

Além de retornar dados, uma API utiliza códigos de status para indicar o resultado de uma requisição.

Alguns dos mais comuns são:

Código	Significado
200	OK — requisição realizada com sucesso
201	Created — recurso criado
204	No Content — sucesso sem corpo de resposta
400	Bad Request — requisição inválida
401	Unauthorized — autenticação necessária ou inválida
403	Forbidden — acesso proibido
404	Not Found — recurso não encontrado
405	Method Not Allowed — método não permitido
422	Unprocessable Content — dados semanticamente inválidos
500	Internal Server Error — erro interno

Utilizar os códigos corretamente facilita a integração entre diferentes aplicações.

Como criar uma API REST com PHP puro?

Agora vamos colocar os conceitos em prática.

Criaremos uma pequena API de produtos com as seguintes funcionalidades:

1. Listar produtos.

2. Consultar um produto pelo ID.

3. Cadastrar um produto.

4. Atualizar um produto.

5. Excluir um produto.

Tudo isso utilizando apenas recursos nativos do PHP.

Passo 1 — Criar o projeto

Crie uma pasta chamada api-php e, dentro dela, um arquivo index.php.

A estrutura será:

api-php/
├── index.php
└── produtos.json

No arquivo produtos.json, coloque inicialmente:

[]

Esse arquivo será utilizado como armazenamento simples para o nosso exemplo.

Atenção: armazenar dados em JSON é adequado para aprendizado, mas não substitui um banco de dados em aplicações de produção. O exemplo também não implementa autenticação ou controle de acesso.

Passo 2 — Criar a API

Abra o arquivo index.php e adicione:

<?php
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
$arquivo = __DIR__ . '/produtos.json';
$metodo = $_SERVER['REQUEST_METHOD'];
$caminho = parse_url(
    $_SERVER['REQUEST_URI'],
    PHP_URL_PATH
);
$caminho = rtrim($caminho, '/') ?: '/';
function responder(int $status, mixed $dados = null): never
{
    http_response_code($status);
    if ($status !== 204) {
        echo json_encode(
            $dados,
            JSON_UNESCAPED_UNICODE |
            JSON_UNESCAPED_SLASHES
        );
    }
    exit;
}
function lerProdutos(string $arquivo): array
{
    $conteudo = file_get_contents($arquivo);
    if ($conteudo === false) {
        responder(500, ['erro' => 'Falha ao ler dados']);
    }
    $dados = json_decode($conteudo, true);
    if (!is_array($dados)) {
        responder(500, ['erro' => 'Dados inválidos']);
    }
    return $dados;
}
function salvarProdutos(string $arquivo, array $produtos): void
{
    $json = json_encode(
        array_values($produtos),
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE
    );
    if ($json === false ||
        file_put_contents($arquivo, $json, LOCK_EX) === false) {
        responder(500, ['erro' => 'Falha ao salvar dados']);
    }
}
function lerCorpo(): array
{
    $conteudo = file_get_contents('php://input');
    $dados = json_decode($conteudo ?: '', true);
    if (!is_array($dados) || array_is_list($dados)) {
        responder(400, ['erro' => 'Envie um objeto JSON válido']);
    }
    if (
        !isset($dados['nome'], $dados['preco']) ||
        !is_string($dados['nome']) ||
        trim($dados['nome']) === '' ||
        !is_numeric($dados['preco']) ||
        !is_finite((float) $dados['preco']) ||
        (float) $dados['preco'] < 0
    ) {
        responder(422, ['erro' => 'Nome ou preço inválido']);
    }
    return [
        'nome' => trim($dados['nome']),
        'preco' => (float) $dados['preco']
    ];
}
if (!preg_match('#^/api/produtos(?:/([1-9][0-9]*))?$#', $caminho, $matches)) {
    responder(404, ['erro' => 'Rota não encontrada']);
}
$id = isset($matches[1]) ? (int) $matches[1] : null;
$permitidos = $id === null
    ? ['GET', 'POST']
    : ['GET', 'PUT', 'DELETE'];
header('Allow: ' . implode(', ', $permitidos));
if (!in_array($metodo, $permitidos, true)) {
    responder(405, ['erro' => 'Método não permitido']);
}
$produtos = lerProdutos($arquivo);
$indice = null;
if ($id !== null) {
    foreach ($produtos as $chave => $produto) {
        if ($produto['id'] === $id) {
            $indice = $chave;
            break;
        }
    }
    if ($indice === null) {
        responder(404, ['erro' => 'Produto não encontrado']);
    }
}
switch ($metodo) {
    case 'GET':
        if ($id === null) {
            responder(200, $produtos);
        }
        responder(200, $produtos[$indice]);
    case 'POST':
        $dados = lerCorpo();
        $ids = array_column($produtos, 'id');
        $novoId = $ids ? max($ids) + 1 : 1;
        $produto = [
            'id' => $novoId,
            ...$dados
        ];
        $produtos[] = $produto;
        salvarProdutos($arquivo, $produtos);
        header('Location: /api/produtos/' . $novoId);
        responder(201, $produto);
    case 'PUT':
        $dados = lerCorpo();
        $produtos[$indice] = [
            'id' => $id,
            ...$dados
        ];
        salvarProdutos($arquivo, $produtos);
        responder(200, $produtos[$indice]);
    case 'DELETE':
        array_splice($produtos, $indice, 1);
        salvarProdutos($arquivo, $produtos);
        responder(204);
}

O exemplo utiliza recursos compatíveis com PHP 8.1 ou superior.

Ele também usa uma implementação simplificada de persistência em arquivo. O bloqueio LOCK_EX protege a escrita individual, mas não torna atômica toda a sequência de leitura e alteração. Portanto, requisições simultâneas podem causar perda de atualizações.

Passo 3 — Iniciar o servidor PHP

Abra o terminal na pasta do projeto e execute:

php -S localhost:8000 index.php

O servidor de desenvolvimento do PHP ficará disponível em:

http://localhost:8000

Esse servidor é destinado ao desenvolvimento local, não à publicação em produção.

Passo 4 — Testar a API

Podemos testar os endpoints utilizando o terminal e o comando curl.

Listar produtos:

curl http://localhost:8000/api/produtos

A resposta inicial será:

[]

Cadastrar um produto:

curl -X POST http://localhost:8000/api/produtos
  -H "Content-Type: application/json"
  -d '{"nome":"Notebook","preco":3500}'

Resposta:

{
  "id": 1,
  "nome": "Notebook",
  "preco": 3500
}

Consultar um produto:

curl http://localhost:8000/api/produtos/1

Atualizar um produto:

curl -X PUT http://localhost:8000/api/produtos/1
  -H "Content-Type: application/json"
  -d '{"nome":"Notebook Gamer","preco":5000}'

Excluir um produto:

curl -X DELETE http://localhost:8000/api/produtos/1

Pronto! Você criou uma API HTTP com operações CRUD usando PHP puro.

Quais são as vantagens de criar APIs com PHP puro?

Desenvolver uma API sem framework pode oferecer alguns benefícios, especialmente em projetos pequenos e para fins de aprendizado.

Maior compreensão do funcionamento

Ao criar uma API com PHP puro, você entende melhor como funcionam as requisições HTTP, os headers, os métodos e as respostas JSON.

Menos dependências

Não é necessário instalar bibliotecas ou frameworks para criar endpoints simples.

Controle sobre o código

O desenvolvedor tem controle direto sobre o roteamento, processamento e formato das respostas.

Bom para projetos pequenos

APIs pequenas e com requisitos limitados podem ser implementadas com poucos arquivos.

Quais são as desvantagens de usar PHP puro?

Apesar das vantagens, trabalhar sem frameworks também apresenta desafios.

Mais código manual: você precisa implementar funcionalidades como roteamento, validação e tratamento de erros.

Segurança: autenticação, autorização, limites de requisições e outras proteções precisam ser planejados e implementados.

Manutenção: conforme a aplicação cresce, manter tudo organizado pode se tornar mais difícil.

Escalabilidade: projetos maiores podem exigir uma arquitetura mais elaborada e infraestrutura adequada.

Por esses motivos, frameworks podem ser úteis em aplicações mais complexas.

Qual a diferença entre API REST e API RESTful?

Os termos são frequentemente utilizados como sinônimos, mas existe uma distinção conceitual.

REST é o estilo arquitetural que define princípios e restrições.

Uma API RESTful é uma API projetada para respeitar esses princípios.

Na prática, muitas APIs são chamadas de REST apenas por utilizarem HTTP, URLs e JSON, mesmo sem seguir todas as restrições da arquitetura.

Vale lembrar que utilizar JSON e os métodos GET, POST, PUT e DELETE não é suficiente, por si só, para garantir conformidade com REST.

API REST precisa de banco de dados?

Não.

Uma API REST pode obter informações de diferentes fontes, como:

• Bancos de dados.

• Arquivos JSON.

• Serviços externos.

• Sistemas internos.

• Informações calculadas em tempo real.

No nosso exemplo, utilizamos um arquivo JSON para simplificar o aprendizado.

Em uma aplicação real, um banco de dados como MySQL ou PostgreSQL pode ser mais adequado para armazenar e consultar informações com segurança e consistência.

API REST é segura?

Uma API REST pode ser segura, mas isso depende de sua implementação.

Algumas boas práticas incluem:

• Utilizar HTTPS.

• Implementar autenticação e autorização.

• Validar todos os dados recebidos.

• Evitar expor informações sensíveis.

• Utilizar consultas parametrizadas ao acessar bancos de dados.

• Configurar limites de requisições.

• Manter o PHP atualizado.

• Registrar erros sem revelar detalhes internos aos clientes.

O exemplo deste artigo é educacional e não deve ser exposto publicamente sem proteções adicionais.

Vale a pena aprender a criar APIs com PHP puro?

Sim, especialmente se você está começando no desenvolvimento backend.

Criar uma API sem framework ajuda a compreender os fundamentos que também são utilizados por ferramentas mais avançadas.

Depois de dominar conceitos como HTTP, JSON, endpoints, métodos e códigos de status, você terá uma base mais sólida para trabalhar com frameworks e arquiteturas maiores.

Conclusão

Uma API REST permite que diferentes sistemas se comuniquem utilizando princípios arquiteturais bem definidos, frequentemente por meio do protocolo HTTP.

Ela pode ser utilizada em aplicativos, sites, plataformas de comércio eletrônico, sistemas administrativos e diversas outras soluções.

Neste artigo, você aprendeu os conceitos fundamentais de uma API REST e viu como criar endpoints utilizando apenas PHP puro.

Se você está começando, experimente ampliar o exemplo, adicionando um banco de dados MySQL, validações mais completas e autenticação.

Esses são excelentes próximos passos para evoluir seus conhecimentos em desenvolvimento backend.