O que é uma API REST?

Uma API REST é uma API que segue o estilo arquitetural REST: recursos em URLs, requisições stateless e métodos HTTP padrão. REST — Representational State Transfer, definido na tese de doutorado de Roy Fielding, de 2000 — é um estilo, não um protocolo ou padrão: um conjunto de restrições que, honradas em conjunto, produzem APIs que a web inteira já sabe consumir, cachear e escalar.

Principais pontos

Um ciclo CRUD completo em HTTP puro

O estilo inteiro em quatro requisições — isto é o que todo framework e SDK envia no fim das contas:

POST /v1/posts                     →  201 Created            criar
{ "title": "Hello REST" }             Location: /v1/posts/8fk2

GET /v1/posts/8fk2                 →  200 OK                 ler
                                      { "title": "Hello REST", … }

PUT /v1/posts/8fk2                 →  200 OK                 substituir
{ "title": "Hello again" }            (PATCH atualizaria campos)

DELETE /v1/posts/8fk2              →  204 No Content         excluir
GET /v1/posts/8fk2                 →  404 Not Found          …e sumiu

O mesmo ciclo por SDKs que embrulham as chamadas REST:

// JavaScript / Node.js — Back4app JS SDK
// The REST semantics, wrapped: create, read, update, delete
const post = new Parse.Object('Post');
post.set('title', 'Hello REST');
await post.save();                            // POST   /classes/Post      → 201

const fetched = await new Parse.Query('Post')
  .get(post.id);                              // GET    /classes/Post/:id  → 200

fetched.set('title', 'Hello again');
await fetched.save();                         // PUT    /classes/Post/:id  → 200

await fetched.destroy();                      // DELETE /classes/Post/:id  → 200

// Flutter / Dart — Back4app Flutter SDK
// The REST semantics, wrapped: create, read, update, delete
final post = ParseObject('Post')..set('title', 'Hello REST');
await post.save();          // POST   /classes/Post      → 201

await post.fetch();         // GET    /classes/Post/:id  → 200

post.set('title', 'Hello again');
await post.save();          // PUT    /classes/Post/:id  → 200

await post.delete();        // DELETE /classes/Post/:id  → 200

// iOS / Swift — Back4app Swift SDK
// The REST semantics, wrapped: create, read, update, delete
var post = Post()
post.title = "Hello REST"
let saved = try await post.save()      // POST   /classes/Post      → 201

let fetched = try await saved.fetch()  // GET    /classes/Post/:id  → 200

var updated = fetched
updated.title = "Hello again"
_ = try await updated.save()           // PUT    /classes/Post/:id  → 200

try await updated.delete()             // DELETE /classes/Post/:id  → 200

// Android / Kotlin — Back4app Android SDK
// The REST semantics, wrapped: create, read, update, delete
val post = ParseObject("Post")
post.put("title", "Hello REST")
post.save()                                    // POST   /classes/Post      → 201

val fetched = ParseQuery.getQuery<ParseObject>("Post")
    .get(post.objectId)                        // GET    /classes/Post/:id  → 200

fetched.put("title", "Hello again")
fetched.save()                                 // PUT    /classes/Post/:id  → 200

fetched.delete()                               // DELETE /classes/Post/:id  → 200

As seis restrições do REST

1. Cliente-servidor — interface e implementação evoluem de forma independente; a UI nunca sabe como o armazenamento funciona.
2. Stateless — cada requisição é autossuficiente; o servidor não guarda sessão entre chamadas, e é isso que deixa qualquer réplica responder qualquer requisição.
3. Cacheável — as respostas declaram a própria cacheabilidade; GETs com os headers de cache corretos colocam toda a infraestrutura de cache da web (navegadores, CDNs, proxies) para trabalhar pela sua API.
4. Interface uniforme — a restrição que é o REST, em quatro partes: recursos identificados por URIs; manipulação por representações (você devolve o JSON que quer que o recurso se torne); mensagens autodescritivas (método + headers dizem tudo o que é preciso para processar a requisição); e hipermídia como motor do estado da aplicação (as respostas linkam as próximas ações).
5. Sistema em camadas — clientes não sabem se estão falando com a origem, um cache ou um gateway; intermediários se encaixam livremente.
6. Código sob demanda (opcional) — servidores podem enviar código executável aos clientes; a única restrição marcada como opcional, e a que a maioria das APIs ignora.

Métodos HTTP: segurança, idempotência, CRUD

A tabela que falta em quase toda página bem ranqueada — as semânticas da RFC 9110, condensadas:

Seguro significa que a requisição não muda nada; idempotente significa que repeti-la não muda nada além. Isso não é curiosidade — é a política de retry: um timeout de rede em um PUT pode ser repetido sem medo, o mesmo timeout em um POST precisa de uma chave de idempotência ou de uma checagem de duplicata. O mapeamento CRUD completo tem verbete próprio.

Códigos de status: o que retornar quando

As distinções 401/403 e 200/201/204 são onde o capricho de API aparece: códigos precisos tornam clientes depuráveis com nada além da linha de status.

Sua API é mesmo REST? A escada de maturidade

A seção honesta que os explicadores comerciais omitem. O Richardson Maturity Model dá nota a APIs HTTP: nível 0 (uma URL, um verbo, RPC disfarçado), nível 1 (recursos em URLs), nível 2 (métodos e códigos de status corretos), nível 3 (hipermídia — HATEOAS).

Pela própria insistência de Fielding, uma API sem hipermídia não é REST — ele escreveu um ensaio afiado dizendo exatamente isso. Na prática, quase toda “API REST” aclamada é uma API HTTP de nível 2: recursos, verbos, códigos de status, JSON, nenhuma hipermídia. Isso importa menos como pureza e mais como vocabulário — conhecer a escada diz o que o termo significa em uma vaga de emprego (nível 2) versus na tese (nível 3), e evita tanto o HATEOAS de cargo cult quanto as correções pedantes.

REST vs. SOAP vs. GraphQL vs. gRPC

A comparação com GraphQL tem um verbete inteiro só dela.

Convenções que tornam uma API REST agradável

Além das restrições, as convenções pelas quais os consumidores silenciosamente dão nota: recursos como substantivos no plural (/posts, não /getPost); aninhamento de um nível no máximo (/posts/8fk2/comments, e pare aí); paginação em toda coleção — baseada em cursor para profundidade e estabilidade, com limites impostos; filtro e ordenação como parâmetros de query, não variantes de endpoint; versionamento com política explícita (caminho /v1/ ou header — escolha um, publique janelas de descontinuação); negociação de conteúdo honrada (Accept, Content-Type); e erros como JSON estruturado com um código legível por máquina, não só prosa. Nada disso está na tese; tudo isso está na diferença entre uma API que desenvolvedores recomendam e uma que eles aturam.

Casos de uso comuns

• APIs públicas e de parceiros — a ubiquidade do REST é o recurso: toda linguagem, ferramenta e desenvolvedor o fala.
• Backends de apps mobile e web — CRUD de recursos sobre HTTP casa com a forma como a maioria das telas de app realmente consome dados.
• Costuras entre microsserviços — contratos internos onde o ferramental do HTTP (gateways, tracing, cache) paga o próprio salário.
• Integrações no estilo webhook — sistemas notificando sistemas com chamadas HTTP simples que os dois lados já entendem.
• APIs de dados geradas automaticamente — plataformas que expõem um banco de dados como recursos REST — o caminho mais rápido do schema à API funcionando.

Você deveria usar REST? Matriz de decisão

Limitações e trade-offs

• Representações fixas servem mal a clientes diversos. O par overfetching/underfetching é a fraqueza estrutural do REST; sparse fieldsets e parâmetros de expansão mitigam, GraphQL redesenha.
• Nenhum contrato obrigatório. Nada força uma spec OpenAPI, então muitas APIs REST são documentadas por folclore; a disciplina é opcional onde gRPC e GraphQL a tornam estrutural.
• Statelessness repete contexto. Auth e contexto de tenant viajam em cada requisição — barato em bytes, mas empurra a semântica de sessão para tokens e torna alguns fluxos (transações em múltiplos passos) desajeitados.
• Tentação do N+1 por design. Pensar recurso-por-URL convida clientes de uma chamada por item; APIs boas entregam expansão e batch antes que os consumidores improvisem loops.
• A palavra “REST” é ambígua. API HTTP de nível 2 na boca da maioria, arquitetura de hipermídia na tese — entenda qual das duas uma spec, vaga ou revisor quer dizer antes de discutir.

APIs REST no Back4app

O Back4app é uma plataforma open-source de Backend as a Service (BaaS) que combina banco de dados gerenciado, APIs REST e GraphQL geradas automaticamente, autenticação, armazenamento de arquivos e funções serverless com Cloud Code. A API REST aqui é gerada, não construída: cada classe do seu modelo de dados é imediatamente um recurso — POST /classes/Post cria, GET /classes/Post/:id lê, com os métodos, códigos de status e a semântica de Location do passo a passo acima — atrás de chaves, tokens de usuário e permissões por classe fazendo valer a fronteira. Os code tabs mostram o mesmo ciclo pelos SDKs, que são embrulhos idiomáticos finos sobre exatamente este HTTP; quando uma operação cresce além do CRUD, uma função de Cloud Code adiciona um endpoint customizado em um arquivo. REST de nível 2, correto por padrão, do schema à URL no tempo de definir a classe.