A API REST (Representational State Transfer) é um estilo arquitetural para construção de APIs web que utiliza métodos HTTP padronizados, URLs como identificadores de recursos e troca de dados normalmente em formato JSON. Criada por Roy Fielding em sua tese de doutorado em 2000, a arquitetura REST se tornou o padrão dominante para integração entre sistemas distribuídos, alimentando desde aplicativos móveis até integrações entre microsserviços corporativos.
TL;DR
- O que é: API REST é um estilo arquitetural baseado em recursos identificados por URLs, manipulados via métodos HTTP (GET, POST, PUT, DELETE) e geralmente em formato JSON.
- Por que importa: É o padrão de fato para APIs web modernas — segundo a Postman State of the API Report (2023), 86% dos desenvolvedores trabalham com REST, ultrapassando GraphQL e SOAP.
- Quando usar: Em integrações públicas, microsserviços, mobile backends e qualquer cenário que exija simplicidade, cacheabilidade e escalabilidade horizontal.
Como funciona uma API REST?
API REST é um estilo arquitetural de APIs baseado em recursos e métodos HTTP padronizados.
Uma API REST funciona expondo recursos (entidades de negócio como clientes, produtos, pedidos) através de URLs únicas e permitindo que clientes manipulem esses recursos usando os verbos HTTP padrão. O cliente envia uma requisição HTTP contendo método, URL, cabeçalhos e corpo opcional; o servidor processa a requisição e devolve uma resposta com código de status, cabeçalhos e payload, geralmente em JSON. Toda comunicação é stateless, ou seja, cada requisição contém todas as informações necessárias para ser processada.
Recursos
Em REST, tudo é tratado como recurso. Um recurso é uma abstração de qualquer informação manipulável: um cliente, um pedido, uma imagem, uma coleção de produtos. Cada recurso possui uma URL canônica que serve como seu identificador único. Por exemplo, em uma API de e-commerce, o recurso de pedido 12345 teria a URL /pedidos/12345, enquanto a coleção completa de pedidos estaria em /pedidos. Segundo Roy Fielding (2000), a abstração de recursos é o conceito central que diferencia REST de RPC.
Métodos HTTP
REST utiliza os métodos HTTP definidos na RFC 7231 (2014) para indicar a operação desejada sobre o recurso. GET busca informações, POST cria novos recursos, PUT substitui um recurso existente, PATCH atualiza parcialmente e DELETE remove. Essa padronização elimina ambiguidade e permite que ferramentas, proxies e caches HTTP entendam a semântica da requisição sem precisar interpretar o corpo da mensagem.
Status codes
As respostas REST utilizam códigos de status HTTP padronizados para sinalizar o resultado. Códigos 2xx indicam sucesso (200 OK, 201 Created, 204 No Content), 3xx redirecionamento, 4xx erro do cliente (400 Bad Request, 401 Unauthorized, 404 Not Found, 422 Unprocessable Entity) e 5xx erro do servidor (500 Internal Server Error, 503 Service Unavailable). Segundo a documentação oficial da Stripe (2024), usar status codes corretamente é essencial para que integradores construam tratamento de erros robusto.
Para que serve uma API REST?
API REST serve para expor funcionalidades e dados de um sistema de forma padronizada para que outros sistemas possam consumi-los via HTTP.
APIs REST viabilizam integrações entre sistemas heterogêneos, sustentam arquiteturas de microsserviços, alimentam aplicativos móveis com dados de backends corporativos e permitem que empresas exponham serviços para parceiros externos através de APIs públicas. Segundo a Postman (2023), uma empresa média consome ou produz mais de 25 APIs diferentes em sua operação diária, das quais a esmagadora maioria é REST.
Casos típicos incluem: backends de aplicativos móveis e SPAs (Single Page Applications), integrações entre CRM e ERP, webhooks de gateways de pagamento, comunicação entre microsserviços internos, APIs públicas como GitHub API e Stripe API, e automações de marketing entre RD Station, HubSpot e sistemas próprios. Em todos esses cenários, REST oferece simplicidade, cacheabilidade nativa via HTTP e tooling maduro.
Os 6 princípios REST (Roy Fielding)
Roy Fielding (2000) definiu seis restrições arquiteturais que uma API precisa respeitar para ser considerada verdadeiramente RESTful. Ignorar essas restrições resulta no que a comunidade chama de REST-like ou HTTP API — funcional, mas sem os benefícios plenos de escalabilidade e evolutibilidade do REST puro.
- Cliente-servidor: Separação clara de responsabilidades. O cliente cuida da interface; o servidor cuida do armazenamento e processamento. Isso permite evolução independente de ambos os lados.
- Stateless (sem estado): Cada requisição deve conter todas as informações necessárias para ser processada. O servidor não mantém contexto de sessões entre chamadas, o que facilita escalabilidade horizontal e balanceamento de carga.
- Cacheável: Respostas devem indicar se podem ser armazenadas em cache e por quanto tempo, através de cabeçalhos como Cache-Control e ETag. Caching agressivo reduz latência e carga no servidor.
- Sistema em camadas: O cliente não precisa saber se está falando diretamente com o servidor final ou com um intermediário (proxy, load balancer, CDN). Isso permite arquiteturas escaláveis com múltiplas camadas de infraestrutura.
- Código sob demanda (opcional): O servidor pode enviar código executável para o cliente, como JavaScript, estendendo funcionalidades dinamicamente. É o único princípio opcional.
- Interface uniforme: Recursos são identificados por URLs, manipulação ocorre via representações (JSON, XML), mensagens são autodescritivas e HATEOAS (Hypermedia as the Engine of Application State) guia o cliente através de links.
Métodos HTTP em REST
A tabela abaixo resume os métodos HTTP mais utilizados em APIs REST, suas semânticas e propriedades segundo a RFC 7231 (2014).
| Método | Operação | Idempotente | Seguro | Exemplo |
|---|---|---|---|---|
| GET | Recuperar recurso | Sim | Sim | GET /clientes/123 |
| POST | Criar recurso | Não | Não | POST /clientes |
| PUT | Substituir recurso completo | Sim | Não | PUT /clientes/123 |
| PATCH | Atualizar parcialmente | Não | Não | PATCH /clientes/123 |
| DELETE | Remover recurso | Sim | Não | DELETE /clientes/123 |
Idempotente significa que múltiplas chamadas idênticas produzem o mesmo resultado da primeira. Seguro significa que a operação não altera o estado do servidor. Respeitar essas propriedades é crítico: GET nunca deve modificar dados, e PUT/DELETE devem ser idempotentes para que retentativas automáticas em redes instáveis não causem efeitos colaterais.
REST vs GraphQL vs SOAP
A escolha entre REST, GraphQL e SOAP impacta diretamente complexidade de implementação, performance e experiência do desenvolvedor consumidor. A tabela abaixo compara as três abordagens nas dimensões mais relevantes.
| Dimensão | REST | GraphQL | SOAP |
|---|---|---|---|
| Formato | JSON (padrão) | JSON | XML |
| Protocolo | HTTP | HTTP | HTTP, SMTP, TCP |
| Endpoints | Múltiplos (por recurso) | Único | Único (SOAP envelope) |
| Over-fetching | Comum | Eliminado | Comum |
| Curva de aprendizado | Baixa | Média | Alta |
| Cacheabilidade HTTP | Nativa | Limitada | Limitada |
| Ferramental | Maduro e abundante | Em crescimento | Corporativo legado |
| Caso de uso ideal | APIs públicas, microsserviços | Frontends complexos | Sistemas corporativos legados |
Segundo a Postman State of the API Report (2023), REST ainda domina com 86% de adoção, seguido por webhooks (36%), GraphQL (29%) e SOAP (26%). A escolha depende do contexto: REST para a maioria dos casos, GraphQL quando o cliente precisa de flexibilidade na seleção de campos, SOAP apenas quando exigido por integrações corporativas legadas.
Erros comuns no design de API REST
A experiência da Shiftmind em projetos de integração B2B mostra que a maioria dos problemas em APIs não vem da tecnologia, mas do design. Os erros abaixo são recorrentes:
- Verbos na URL em vez de substantivos: URLs como /getCliente ou /criarPedido violam REST. O correto é usar substantivos (recursos) com métodos HTTP indicando a ação: GET /clientes/123 e POST /pedidos.
- Ignorar status codes HTTP: Retornar 200 OK com um campo de erro no corpo é antipattern clássico. Use 4xx para erros do cliente e 5xx para falhas do servidor. Segundo a Stripe (2024), status codes corretos são essenciais para tratamento automático de erros em SDKs.
- Falta de versionamento: Lançar uma API sem estratégia de versionamento (/v1/, /v2/) trava a evolução. Quebrar contratos sem aviso prévio destrói a confiança de integradores.
- Paginação ausente: Endpoints que retornam coleções inteiras sem paginação quebram em produção. Use offset/limit ou cursor-based pagination desde o dia um.
- Ausência de rate limiting: APIs sem rate limiting ficam vulneráveis a abuso e indisponibilidade. A GitHub API (2024) limita a 5.000 requisições por hora por token autenticado, comunicando o limite via cabeçalhos X-RateLimit-*.
- Documentação pobre ou desatualizada: Segundo a Postman (2023), 58% dos desenvolvedores citam documentação ruim como principal obstáculo na integração. Use OpenAPI (Swagger) e mantenha a documentação sincronizada com o código.
- Mensagens de erro vagas: Retornar apenas um genérico Erro interno sem código, campo problemático ou orientação frustra integradores. Adote padrões como RFC 7807 (Problem Details for HTTP APIs).
- Acoplamento de campos sensíveis: Expor todos os campos do banco automaticamente vaza dados. Defina explicitamente o contrato de cada endpoint.
API REST e a Shiftmind
A Shiftmind trabalha com APIs REST há mais de 12 anos em projetos de integração B2B, conectando CRMs, ERPs, plataformas de marketing e sistemas customizados de clientes industriais e de serviços. Nossa abordagem combina criação de sites WordPress que consomem e expõem APIs REST nativas, desenvolvimento WordPress com endpoints customizados via WP REST API, e arquiteturas de e-commerce B2B que integram catálogos, estoques e pedidos com sistemas ERP corporativos.
O suporte e manutenção contínuos garantem que integrações REST permaneçam funcionais após atualizações de plugins e mudanças de versão em APIs de terceiros. A segurança de websites inclui hardening específico para endpoints REST: rate limiting, validação de tokens, proteção contra abuso de endpoints públicos e auditoria de logs. Cada projeto da Shiftmind é entregue com documentação OpenAPI, testes automatizados e monitoramento de SLA.
Perguntas frequentes sobre API REST
Qual a diferença entre REST e RESTful?
REST é o estilo arquitetural definido por Roy Fielding (2000); RESTful é o adjetivo que descreve sistemas que aderem a esse estilo. Na prática, os termos são usados de forma intercambiável, mas existe distinção técnica: uma API é verdadeiramente RESTful apenas quando respeita as seis restrições arquiteturais, incluindo HATEOAS. A maioria das APIs comerciais chamadas de REST são tecnicamente REST-like ou HTTP APIs, pois ignoram HATEOAS. Isso não é problema na prática, desde que o time esteja ciente da nomenclatura correta.
REST sempre usa JSON?
Não. REST é agnóstico em relação ao formato de payload. Pode usar JSON, XML, YAML, Protocol Buffers ou qualquer outro formato. Na prática, JSON dominou por simplicidade e suporte nativo em JavaScript. Segundo a Postman (2023), mais de 95% das APIs REST modernas usam JSON como formato primário. APIs corporativas legadas ainda usam XML, e algumas APIs de alta performance adotam Protocol Buffers ou MessagePack para reduzir tamanho de payload. O cabeçalho Content-Type indica o formato em cada requisição e resposta.
Como autenticar uma API REST?
As estratégias mais comuns são: API Keys (tokens estáticos enviados em cabeçalhos), OAuth 2.0 (padrão para autorização delegada, usado por Google, GitHub e Microsoft), JWT (JSON Web Tokens autocontidos com claims assinados) e Basic Auth (apenas para uso interno em HTTPS). Para APIs públicas modernas, OAuth 2.0 com JWT é o padrão de mercado. A Stripe API (2024) usa API Keys com prefixos sk_live_ e pk_test_ que permitem rotacionamento granular. Sempre use HTTPS, nunca exponha credenciais em URLs e implemente rotação periódica de tokens.
Quando usar PUT versus PATCH?
Use PUT quando precisar substituir o recurso completo — todos os campos do payload sobrescrevem o estado atual. Use PATCH quando precisar atualizar apenas alguns campos sem afetar os demais. Segundo a RFC 7231 (2014), PUT é idempotente porque envia o estado completo; PATCH pode ou não ser idempotente, dependendo da semântica da operação. Na prática, PATCH é mais eficiente em redes lentas e em payloads grandes, mas exige documentação clara do formato (JSON Patch, JSON Merge Patch). PUT é mais simples e previsível.
API REST funciona em microsserviços?
Sim. REST é uma das tecnologias de comunicação mais usadas em arquiteturas de microsserviços, especialmente para comunicação síncrona entre serviços. Cada microsserviço expõe sua API REST, e outros serviços consomem via HTTP. Segundo a CNCF (2024), aproximadamente 70% das comunicações síncronas entre microsserviços usam REST ou gRPC. Para comunicação assíncrona, message brokers (Kafka, RabbitMQ) são preferíveis. REST funciona bem em microsserviços porque é stateless, cacheável e tem ferramental maduro para observabilidade, tracing distribuído e service mesh.
Termos relacionados
- Abstração
- Acoplamento
- ActiveRecord
- Agile (Metodologia Ágil)
- AJAX (Asynchronous JavaScript and XML)
- Algoritmo
- Algoritmo de Busca
- Algoritmo de Ordenação
- Amazon Alexa SDK
- Android
- Android Studio
- Angular
- Anotação
- Anti-Pattern
- Apache Spark
- API Gateway
- API Key
- API Rate Limiting
- API
Conclusão
API REST consolidou-se como o padrão dominante para integração entre sistemas web pela combinação de simplicidade, cacheabilidade nativa via HTTP e ferramental maduro. Dominar os seis princípios de Roy Fielding, os métodos HTTP corretos e os erros comuns de design é o diferencial entre uma API que escala e uma que se torna dívida técnica. REST não é a única opção — GraphQL e gRPC têm seus espaços — mas continua sendo a escolha padrão para a maioria dos projetos B2B.
Última atualização: Junho/2026.
Precisa projetar, integrar ou modernizar APIs REST no seu projeto? A Shiftmind combina experiência em WordPress, e-commerce B2B e integrações corporativas para entregar APIs robustas, documentadas e seguras. Entre em contato e converse com nosso time técnico.
