REST API: o que é, métodos HTTP e princípio de funcionamento em aplicativos móveis

O que é REST API?

REST API (API de Transferência de Estado Representacional) é um estilo arquitetônico proposto por Roy Fielding em sua tese de doutorado em 2000. Ele define um conjunto de restrições e princípios para projetar protocolos de rede. Uma API que cumpre essas restrições é chamada de RESTful. REST não é um protocolo ou padrão — é uma abordagem arquitetônica que utiliza protocolos existentes (principalmente HTTP) para troca de dados entre cliente e servidor.

A ideia chave do REST é a arquitetura orientada a recursos. Em vez de chamar métodos no servidor (como em SOAP ou RPC), o cliente opera sobre recursos: obtém listas, cria novos, atualiza ou exclui. Cada recurso é uma entidade de domínio: usuário, pedido, produto, artigo. Um recurso possui um estado que é transmitido ao cliente em um formato padronizado, geralmente JSON. O servidor não armazena o estado do cliente entre requisições — este é o princípio stateless, um requisito chave do REST.

Características principais da REST API:

• Stateless — cada requisição do cliente contém todas as informações necessárias para seu processamento
• Cacheable — as respostas do servidor devem ser explicitamente marcadas como armazenáveis em cache ou não
• Layered system — a arquitetura pode incluir servidores intermediários, balanceadores de carga, proxies
• Uniform interface — uma interface de interação única através de métodos HTTP, URLs e códigos de status

Princípios da Arquitetura REST

REST baseia-se em seis restrições arquitetônicas formuladas por Fielding. A conformidade com essas restrições garante escalabilidade, desempenho e facilidade de integração. Cada princípio resolve um problema específico de sistemas distribuídos — desde a necessidade de cache até requisitos de segurança. Vamos examinar cada princípio em detalhes.

O princípio Uniform Interface inclui adicionalmente quatro sub-restrições: identificação de recursos via URI, manipulação de recursos através de representações, mensagens autodescritivas e HATEOAS (Hipermídia como Mecanismo do Estado da Aplicação). A última sub-restrição é frequentemente ignorada na prática — a maioria das REST APIs modernas não implementa HATEOAS completamente, o que gera discussões sobre se tal API é “realmente” RESTful.

O princípio Stateless é um dos mais importantes para escalabilidade. A ausência de sessões no servidor significa que qualquer instância do servidor pode processar qualquer requisição. Isso simplifica o escalonamento horizontal: basta adicionar novos servidores atrás de um balanceador de carga. Para aplicativos móveis, stateless também significa que uma requisição pode ser enviada a qualquer servidor CDN, o que é crítico para disponibilidade global.

Métodos HTTP no REST

Cada método HTTP em REST API corresponde a uma operação específica em um recurso: GET para leitura, POST para criação, PUT para atualização completa, PATCH para atualização parcial, DELETE para exclusão. A idempotência dos métodos é uma característica chave: GET, PUT, DELETE são idempotentes (execução repetida produz o mesmo resultado), POST e PATCH não são. Isso é importante para lidar com erros de rede quando o cliente não sabe se a requisição chegou ao servidor.

• GET — obtenção de um recurso ou lista de recursos. Idempotente, não altera o estado do servidor
• POST — criação de um novo recurso. Não idempotente, cada chamada cria um novo recurso
• PUT — substituição completa do recurso. Idempotente, chamadas repetidas não alteram o estado após a primeira
• PATCH — atualização parcial do recurso. Parcialmente idempotente (depende da implementação)
• DELETE — exclusão do recurso. Idempotente, exclusão repetida retorna 404, não um erro

Os códigos de status HTTP são parte integrante da REST API. Cada código carrega um significado específico: 200 OK para GET bem-sucedido, 201 Created para POST, 204 No Content para DELETE sem corpo de resposta, 400 Bad Request para dados inválidos, 401 Unauthorized para falta de autenticação, 404 Not Found para recurso inexistente. O uso correto dos códigos de status torna a API autodocumentada e simplifica a depuração.

Formatos de dados: JSON e outros

JSON (Notação de Objetos JavaScript) é o formato principal de transferência de dados em REST API. Sua popularidade se deve à simplicidade, legibilidade humana e suporte nativo em JavaScript. JSON é transmitido com o cabeçalho Content-Type: application/json. Alternativas incluem XML (verboso, envelhecendo), YAML (conveniente para configuração, menos comum para APIs) e Protocol Buffers (binário, eficiente para sistemas de alta carga).

A estrutura de um objeto JSON em REST API geralmente inclui campos id, type e atributos do recurso. Para coleções, usa-se um array JSON com metadados de paginação. REST APIs modernas seguem a especificação JSON:API (jsonapi.org) ou JSON Schema para validação de respostas. O uso de um formato de dados unificado simplifica o desenvolvimento de bibliotecas cliente e a geração de documentação.

Exemplo de resposta JSON para uma lista de usuários:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

A escolha do formato de transferência de dados afeta o desempenho do aplicativo móvel. JSON comprime via GZIP em 70-80%, tornando-o aceitável para a maioria dos cenários. Para aplicações em tempo real com grandes volumes de dados (streaming, jogos), recomenda-se mudar para protocolos binários ou usar WebSocket em combinação com Protocol Buffers.

Exemplos de requisições REST API

Vamos ver exemplos práticos de trabalho com REST API no lado do aplicativo móvel. Como exemplo, vamos pegar uma API para trabalhar com pedidos em uma loja online. Para cada método HTTP, são mostrados uma requisição e a resposta esperada do servidor. Os exemplos demonstram a estrutura típica de API RESTful usada no desenvolvimento móvel.

GET — obtendo uma lista de pedidos

Uma requisição para obter todos os pedidos do usuário com paginação. A resposta contém um array de objetos de pedido e meta-informação para navegação entre páginas. Os parâmetros page e per_page são passados via query string.

// Interface Retrofit para REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — criando um novo pedido

Criação de um novo pedido via requisição POST. O servidor retorna o status 201 Created e o objeto criado no corpo da resposta. Importante: a criação é feita na coleção /api/v1/orders, não em um recurso específico — este é o padrão RESTful padrão.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Exemplo de corpo de requisição
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — excluindo um pedido

A exclusão de um recurso é feita com o método DELETE na URL específica do pedido. A exclusão bem-sucedida retorna 204 No Content. A idempotência do DELETE significa que uma requisição repetida à mesma URL retorna 404 Not Found, o que é tratado corretamente no cliente.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Uso no ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Estes exemplos demonstram uma implementação típica de REST API no lado Android usando Retrofit e Kotlin Coroutines. Para aplicativos iOS, o URLSession ou a biblioteca Alamofire em conjunto com protocolos Codable desempenham um papel semelhante. A estrutura da REST API permanece a mesma independentemente da plataforma — apenas o método de fazer requisições muda.

Design de API RESTful: recomendações práticas

Projetar uma API RESTful de qualidade requer seguir convenções que tornem a API intuitiva para os desenvolvedores. Os recursos devem ser nomeados com substantivos no plural (/users, /orders, /products), os métodos HTTP devem refletir operações e as URLs devem representar a hierarquia de aninhamento. Erros devem retornar um JSON padronizado com código e mensagem, não apenas um status HTTP. Seguir estas convenções reduz a barreira de entrada para novos desenvolvedores e simplifica a integração.

• Nomeação de recursos — plural, kebab-case: /api/v1/user-orders, não /api/v1/getUserOrders
• Filtragem e ordenação — via parâmetros query: ?status=active&sort=created_at:desc
• Paginação — baseada em cursor para conjuntos grandes, baseada em página para pequenos
• Versionamento — via URL (/api/v2/) ou cabeçalho Accept-Version
• Erros — formato unificado: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — cabeçalhos X-RateLimit-Remaining e Retry-After

Um erro comum ao projetar uma REST API é o aninhamento excessivo de recursos. Em vez de /users/1/orders/5/items/3, é melhor usar uma estrutura plana com parâmetros query: /items?order_id=5&user_id=1. Isso simplifica o cache, não requer manter caminhos longos no servidor e é mais fácil de documentar. A arquitetura plana também é mais compatível com consultas baseadas em grafo ao migrar para GraphQL no futuro.

A segurança da REST API é implementada através de autenticação (JWT, OAuth 2.0) e autorização no nível de recursos. Cada requisição deve verificar se o usuário tem acesso ao recurso solicitado. HTTPS é obrigatório — sem criptografia, tokens e dados são transmitidos em texto plano. Para aplicativos móveis, recomenda-se usar OAuth 2.0 com PKCE (Proof Key for Code Exchange) para obtenção segura de tokens.

Versionamento e cache

O versionamento de REST API é necessário para compatibilidade reversa durante mudanças. As abordagens mais comuns são: versão na URL (/api/v1/orders), versão no cabeçalho (Accept: application/vnd.myapi.v1+json) e versão no parâmetro query (?api_version=1). O versionamento por URL é o método mais popular pois é explicitamente visível em logs e documentação. No entanto, ele viola o princípio REST de uma URL única por recurso.

O cache em REST API é implementado através dos cabeçalhos HTTP Cache-Control, ETag e Last-Modified. Requisições GET marcadas como armazenáveis em cache podem ser servidas do cache do navegador ou proxy sem contatar o servidor. Para aplicativos móveis, o cache é especialmente importante — reduz o consumo de dados e acelera a exibição de dados previamente carregados com conectividade ruim. ETag é um hash do conteúdo da resposta: o cliente o envia em If-None-Match, e o servidor retorna 304 Not Modified se os dados não mudaram.

Alternativas modernas à REST API incluem GraphQL (busca flexível de dados pelo cliente) e gRPC (protocolo binário sobre HTTP/2 para microsserviços). No entanto, REST continua sendo o padrão principal para APIs públicas devido à sua simplicidade, universalidade e amplo suporte de ferramentas. A escolha entre REST e alternativas depende dos requisitos específicos do projeto: complexidade das consultas, volume de dados, necessidades de atualizações em tempo real.