--- term: 'API REST' seoTitle: 'O que é API REST? Restrições, Métodos e Códigos de Status' headline: 'O que é uma API REST?' slug: api-rest category: api-realtime shortDefinition: 'Uma API REST é uma API que segue o estilo arquitetural REST: recursos em URLs, requisições stateless e métodos HTTP padrão.' relatedTerms: - api - graphql-vs-rest - auto-generated-database-apis - crud-operations contrastsWith: - graphql-vs-rest aboutTerms: - 'REST (Representational State Transfer)' - 'API RESTful' faq: - question: 'O que é uma API REST em termos simples?' answer: 'Uma forma de duas aplicações conversarem por HTTP usando convenções que todo mundo já conhece: cada coisa (um usuário, um pedido) vive em uma URL, você age sobre ela com um verbo padrão — GET para ler, POST para criar, PUT ou PATCH para atualizar, DELETE para remover — e cada requisição se sustenta sozinha, carregando tudo de que o servidor precisa para respondê-la.' - question: 'O que significa REST?' answer: 'Representational State Transfer — transferência de estado representacional —, da tese de doutorado de Roy Fielding, de 2000. O nome descreve o mecanismo: o servidor transfere ao cliente uma representação do estado de um recurso (geralmente JSON), e o cliente move a aplicação de estado em estado por meio dessas representações.' - question: 'Qual a diferença entre REST e RESTful?' answer: 'No uso cotidiano, nenhuma — os termos são intercambiáveis. Sendo pedante, REST nomeia o estilo arquitetural e RESTful é o adjetivo para uma API que o implementa. A afirmação que circula por aí de que "RESTful segue todas as regras e REST só algumas" não tem base nenhuma no trabalho de Fielding.' - question: 'Quais são as seis restrições do REST?' answer: 'Separação cliente-servidor, statelessness, cacheabilidade, interface uniforme, sistema em camadas e — opcionalmente — código sob demanda. A própria interface uniforme se desdobra em quatro regras: recursos identificados por URIs, manipulação por representações, mensagens autodescritivas e hipermídia como motor do estado da aplicação.' - question: 'Qual a diferença entre PUT e POST?' answer: 'Idempotência e endereçamento. POST cria sob uma coleção — o servidor atribui a URL, e repetir a requisição cria duplicatas. PUT escreve uma representação completa em uma URL conhecida — repeti-lo produz o mesmo estado, o que torna retries seguros. Essa diferença de segurança, não de estilo, é o motivo de a distinção importar.' - question: 'Uma API REST precisa usar JSON?' answer: 'Não. REST é agnóstico de formato — um recurso pode ser representado como JSON, XML, HTML ou uma imagem, negociado pelos headers Accept e Content-Type. JSON é apenas o padrão moderno porque todo cliente o interpreta de forma barata. A restrição é sobre representações, não sobre uma em particular.' - question: 'O que significa stateless em uma API REST?' answer: 'O servidor não guarda memória do cliente entre requisições: cada requisição carrega tudo o que é preciso para processá-la, inclusive credenciais como um bearer token. O ganho é escala horizontal — qualquer servidor pode responder qualquer requisição — e o custo é repetir alguns bytes de contexto por chamada.' - question: 'O que é HATEOAS?' answer: 'Hypermedia As The Engine Of Application State: as respostas incluem links para as próximas ações disponíveis, e os clientes navegam a API como pessoas navegam a web — seguindo links em vez de fixar URLs no código. É a restrição menos implementada; a maioria das APIs "REST" de produção a pula e vive feliz no nível 2 do modelo de maturidade.' codeLanguages: [javascript, dart, swift, kotlin] externalAuthorities: - name: 'Fielding dissertation, Chapter 5 — Representational State Transfer' url: 'https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm' - name: 'RFC 9110 — HTTP Semantics' url: 'https://www.rfc-editor.org/rfc/rfc9110' - name: 'HTTP request methods — MDN Web Docs' url: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods' - name: 'Richardson Maturity Model — Martin Fowler' url: 'https://martinfowler.com/articles/richardsonMaturityModel.html' cta: title: 'Uma API REST que você não precisa construir' text: 'Todo modelo de dados do Back4app sai de fábrica como uma API REST — URLs de recurso, métodos e códigos de status corretos, auth e permissões na fronteira — além de SDKs que a embrulham de forma idiomática em todas as plataformas.' linkText: 'Comece grátis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-08-20' translationKey: rest-api --- **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](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) 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 | Pergunta | Resposta | | --- | --- | | O modelo | Recursos em URLs · representações (geralmente JSON) · métodos padrão | | A origem | Tese de Fielding, 2000, capítulo 5 — um estilo arquitetural, não uma spec | | As seis restrições | Cliente-servidor · stateless · cacheável · interface uniforme · em camadas · código sob demanda (opcional) | | Os verbos | GET · POST · PUT · PATCH · DELETE — com semânticas de segurança e idempotência | | A nota de rodapé honesta | A maioria das APIs "REST" de produção são APIs HTTP de nível 2 — e tudo bem | ## 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: ```text 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:** ```javascript // 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 // 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 ``` **Swift:** ```swift // 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 ``` **Kotlin:** ```kotlin // 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("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](/glossary/cdn-content-delivery-network/), 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](https://www.rfc-editor.org/rfc/rfc9110), condensadas: | Método | Papel no CRUD | Seguro? | Idempotente? | Repetir às cegas? | | --- | --- | --- | --- | --- | | GET | Ler | Sim | Sim | Sim | | POST | Criar | Não | **Não** | Não — pode duplicar | | PUT | Substituir | Não | Sim | Sim — mesmo resultado | | PATCH | Atualização parcial | Não | Não garantido | Depende do design do patch | | DELETE | Remover | Não | Sim | Sim — continua removido | *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](/glossary/crud-operations/) completo tem verbete próprio. ## Códigos de status: o que retornar quando | Situação | Retorne | | --- | --- | | Leitura bem-sucedida | 200 OK | | Recurso criado | 201 Created + header `Location` | | Excluído; nada a dizer | 204 No Content | | Requisição malformada | 400 Bad Request | | Sem credenciais ou credenciais inválidas | 401 Unauthorized | | Autenticado mas sem permissão | 403 Forbidden | | Recurso inexistente | 404 Not Found | | Acima do rate limit | 429 Too Many Requests ([detalhes](/glossary/api-rate-limiting-throttling/)) | | Falha do servidor | 500 Internal Server Error | 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](https://martinfowler.com/articles/richardsonMaturityModel.html) 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). ```mermaid flowchart TB accTitle: Richardson Maturity Model para APIs REST accDescr: Quatro níveis, do nível zero, HTTP puro como túnel, passando por recursos, depois verbos HTTP e códigos de status, até os controles de hipermídia do nível três, com a maioria das APIs de produção no nível dois. L0["Nível 0 — um endpoint, POST para tudo (RPC disfarçado)"] --> L1["Nível 1 — recursos: /posts/8fk2"] L1 --> L2["Nível 2 — verbos + códigos de status ← a maioria das APIs de produção vive aqui"] L2 --> L3["Nível 3 — hipermídia: respostas linkam as próximas ações (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 | | REST | SOAP | GraphQL | gRPC | | --- | --- | --- | --- | --- | | Natureza | Estilo arquitetural | Protocolo | Linguagem de consulta + runtime | Framework de RPC | | No fio | JSON sobre HTTP | Envelopes XML | JSON sobre HTTP (um endpoint) | Protobuf sobre HTTP/2 | | Contrato | OpenAPI (convenção) | WSDL (obrigatório) | Schema (embutido) | .proto (obrigatório) | | Cache | Nativo do HTTP — seu superpoder | Fraco | Na aplicação | Na aplicação | | Melhor em | CRUD público de recursos | Formalidade enterprise/legado | Dados aninhados moldados pelo cliente | Velocidade interna entre serviços | | Fraqueza | Formatos fixos [over/underfetch](/glossary/overfetching-underfetching/) | Verbosidade | Complexidade de cache e rate limiting | Atrito no navegador | A [comparação com GraphQL](/glossary/graphql-vs-rest/) 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](/glossary/pt/apis-geradas-automaticamente/) — o caminho mais rápido do schema à API funcionando. ## Você deveria usar REST? Matriz de decisão | REST é o padrão certo quando… | Busque outra coisa quando… | | --- | --- | | API pública, consumidores desconhecidos | Malha interna de alto throughput → gRPC | | Domínio CRUD com formato de recurso | Clientes precisam moldar respostas aninhadas → GraphQL | | O cache HTTP pode carregar a carga de leitura | Push bidirecional em tempo real → [WebSockets](/glossary/websockets-real-time-sync/) / [live queries](/glossary/real-time-live-queries/) | | Simplicidade e amplitude de ferramental importam | Contratos enterprise formais exigidos → SOAP | | As telas mapeiam limpo para recursos | Uma tela agrega cinco serviços → endpoint composto / BFF | ## 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](/glossary/n-plus-one-query-problem/); 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.