REST API: qué es, métodos HTTP y principios de funcionamiento en aplicaciones móviles

¿Qué es REST API?

REST API (API de Transferencia de Estado Representacional) es un estilo arquitectónico propuesto por Roy Fielding en su tesis doctoral en 2000. Define un conjunto de restricciones y principios para diseñar protocolos de red. Una API que cumple con estas restricciones se denomina RESTful. REST no es un protocolo o estándar — es un enfoque arquitectónico que utiliza protocolos existentes (principalmente HTTP) para el intercambio de datos entre cliente y servidor.

La idea clave de REST es la arquitectura orientada a recursos. En lugar de llamar métodos en el servidor (como en SOAP o RPC), el cliente opera sobre recursos: obtiene listas, crea nuevos, actualiza o elimina. Cada recurso es una entidad del dominio: usuario, pedido, producto, artículo. Un recurso tiene un estado que se transmite al cliente en un formato estandarizado, generalmente JSON. El servidor no almacena el estado del cliente entre solicitudes — este es el principio stateless, un requisito clave de REST.

Características principales de REST API:

• Stateless — cada solicitud del cliente contiene toda la información necesaria para su procesamiento
• Cacheable — las respuestas del servidor deben marcarse explícitamente como almacenables en caché o no
• Layered system — la arquitectura puede incluir servidores intermedios, balanceadores de carga, proxies
• Uniform interface — una interfaz de interacción única a través de métodos HTTP, URLs y códigos de estado

Principios de la Arquitectura REST

REST se basa en seis restricciones arquitectónicas formuladas por Fielding. El cumplimiento de estas restricciones garantiza escalabilidad, rendimiento y facilidad de integración. Cada principio resuelve un problema específico de los sistemas distribuidos — desde la necesidad de almacenamiento en caché hasta los requisitos de seguridad. Examinemos cada principio en detalle.

El principio de Uniform Interface incluye adicionalmente cuatro sub-restricciones: identificación de recursos mediante URI, manipulación de recursos a través de representaciones, mensajes autodescriptivos y HATEOAS (Hipermedia como Motor del Estado de la Aplicación). La última sub-restricción a menudo se ignora en la práctica — la mayoría de las API REST modernas no implementan HATEOAS completamente, lo que genera debates sobre si dicha API es “realmente” RESTful.

El principio de Stateless es uno de los más importantes para el escalado. La ausencia de sesiones en el servidor significa que cualquier instancia del servidor puede procesar cualquier solicitud. Esto simplifica el escalado horizontal: basta con añadir nuevos servidores detrás de un balanceador de carga. Para las aplicaciones móviles, stateless también significa que una solicitud puede enviarse a cualquier servidor CDN, lo que es crítico para la disponibilidad global.

Métodos HTTP en REST

Cada método HTTP en REST API corresponde a una operación específica sobre un recurso: GET para lectura, POST para creación, PUT para actualización completa, PATCH para actualización parcial, DELETE para eliminación. La idempotencia de los métodos es una característica clave: GET, PUT, DELETE son idempotentes (la ejecución repetida produce el mismo resultado), POST y PATCH no lo son. Esto es importante para manejar errores de red cuando el cliente no sabe si la solicitud llegó al servidor.

• GET — obtención de un recurso o lista de recursos. Idempotente, no cambia el estado del servidor
• POST — creación de un nuevo recurso. No idempotente, cada llamada crea un nuevo recurso
• PUT — reemplazo completo del recurso. Idempotente, las llamadas repetidas no cambian el estado después de la primera
• PATCH — actualización parcial del recurso. Parcialmente idempotente (depende de la implementación)
• DELETE — eliminación del recurso. Idempotente, la eliminación repetida devuelve 404, no un error

Los códigos de estado HTTP son una parte integral de REST API. Cada código tiene un significado específico: 200 OK para GET exitoso, 201 Created para POST, 204 No Content para DELETE sin cuerpo de respuesta, 400 Bad Request para datos no válidos, 401 Unauthorized para falta de autenticación, 404 Not Found para recurso inexistente. El uso correcto de los códigos de estado hace que la API sea autodocumentada y simplifica la depuración.

Formatos de datos: JSON y otros

JSON (Notación de Objetos JavaScript) es el formato principal de transferencia de datos en REST API. Su popularidad se debe a su simplicidad, legibilidad humana y soporte nativo en JavaScript. JSON se transmite con el encabezado Content-Type: application/json. Las alternativas incluyen XML (verboso, envejecido), YAML (conveniente para configuraciones, menos común para APIs) y Protocol Buffers (binario, eficiente para sistemas de alta carga).

La estructura de un objeto JSON en REST API generalmente incluye campos id, type y atributos del recurso. Para colecciones, se utiliza un array JSON con metadatos de paginación. Las API REST modernas siguen la especificación JSON:API (jsonapi.org) o JSON Schema para la validación de respuestas. El uso de un formato de datos unificado simplifica el desarrollo de bibliotecas cliente y la generación de documentación.

Ejemplo de respuesta JSON para una lista de usuarios:

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

La elección del formato de transferencia de datos afecta el rendimiento de la aplicación móvil. JSON se comprime mediante GZIP en un 70-80%, lo que lo hace aceptable para la mayoría de los escenarios. Para aplicaciones en tiempo real con grandes volúmenes de datos (streaming, juegos), se recomienda cambiar a protocolos binarios o usar WebSocket en combinación con Protocol Buffers.

Ejemplos de solicitudes REST API

Veamos ejemplos prácticos de trabajo con REST API en el lado de la aplicación móvil. Como ejemplo, tomemos una API para trabajar con pedidos en una tienda en línea. Para cada método HTTP se muestran una solicitud y la respuesta esperada del servidor. Los ejemplos demuestran la estructura típica de una API RESTful utilizada en el desarrollo móvil.

GET — obtención de una lista de pedidos

Una solicitud para obtener todos los pedidos de un usuario con paginación. La respuesta contiene un array de objetos de pedido e información meta para la navegación por páginas. Los parámetros page y per_page se pasan mediante query string.

// Interfaz 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 — creación de un nuevo pedido

Creación de un nuevo pedido mediante una solicitud POST. El servidor devuelve el estado 201 Created y el objeto creado en el cuerpo de la respuesta. Importante: la creación se realiza sobre la colección /api/v1/orders, no sobre un recurso específico — este es el patrón RESTful estándar.

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

// Ejemplo de cuerpo de solicitud
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — eliminación de un pedido

La eliminación de un recurso se realiza mediante el método DELETE en la URL específica del pedido. La eliminación exitosa devuelve 204 No Content. La idempotencia de DELETE significa que una solicitud repetida a la misma URL devuelve 404 Not Found, lo que se maneja correctamente en el cliente.

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

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

Estos ejemplos demuestran una implementación típica de REST API en el lado de Android usando Retrofit y Kotlin Coroutines. Para aplicaciones iOS, URLSession o la biblioteca Alamofire junto con los protocolos Codable cumplen un rol similar. La estructura de REST API sigue siendo la misma independientemente de la plataforma — solo cambia la forma de realizar las solicitudes.

Diseño de API RESTful: recomendaciones prácticas

El diseño de una API RESTful de calidad requiere seguir convenciones que hagan la API intuitiva para los desarrolladores. Los recursos deben nombrarse con sustantivos en plural (/users, /orders, /products), los métodos HTTP deben reflejar operaciones y las URLs deben representar la jerarquía de anidamiento. Los errores deben devolver un JSON estandarizado con un código y mensaje, no solo un estado HTTP. El cumplimiento de estas convenciones reduce la barrera de entrada para nuevos desarrolladores y simplifica la integración.

• Nombrado de recursos — plural, kebab-case: /api/v1/user-orders, no /api/v1/getUserOrders
• Filtrado y ordenación — mediante parámetros query: ?status=active&sort=created_at:desc
• Paginación — basada en cursor para conjuntos grandes, basada en página para pequeños
• Versionado — mediante URL (/api/v2/) o cabecera Accept-Version
• Errores — formato unificado: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — cabeceras X-RateLimit-Remaining y Retry-After

Un error frecuente al diseñar una REST API es el anidamiento excesivo de recursos. En lugar de /users/1/orders/5/items/3, es mejor usar una estructura plana con parámetros query: /items?order_id=5&user_id=1. Esto simplifica el almacenamiento en caché, no requiere mantener rutas largas en el servidor y es más fácil de documentar. La arquitectura plana también es más compatible con consultas basadas en grafos al migrar a GraphQL en el futuro.

La seguridad de REST API se implementa mediante autenticación (JWT, OAuth 2.0) y autorización a nivel de recursos. Cada solicitud debe verificar si el usuario tiene acceso al recurso solicitado. HTTPS es obligatorio — sin cifrado, los tokens y datos se transmiten en texto plano. Para aplicaciones móviles, se recomienda usar OAuth 2.0 con PKCE (Proof Key for Code Exchange) para la obtención segura de tokens.

Versionado y almacenamiento en caché

El versionado de REST API es necesario para la compatibilidad hacia atrás durante los cambios. Los enfoques más comunes son: versión en URL (/api/v1/orders), versión en cabecera (Accept: application/vnd.myapi.v1+json) y versión en parámetro query (?api_version=1). El versionado por URL es el método más popular ya que es explícitamente visible en registros y documentación. Sin embargo, viola el principio REST de una URL única por recurso.

El almacenamiento en caché en REST API se implementa mediante las cabeceras HTTP Cache-Control, ETag y Last-Modified. Las solicitudes GET marcadas como almacenables en caché pueden servirse desde la caché del navegador o proxy sin contactar al servidor. Para aplicaciones móviles, el almacenamiento en caché es especialmente importante — reduce el consumo de datos y acelera la visualización de datos previamente cargados con mala conectividad. ETag es un hash del contenido de la respuesta: el cliente lo envía en If-None-Match, y el servidor devuelve 304 Not Modified si los datos no han cambiado.

Las alternativas modernas a REST API incluyen GraphQL (obtención flexible de datos por parte del cliente) y gRPC (protocolo binario sobre HTTP/2 para microservicios). Sin embargo, REST sigue siendo el estándar principal para APIs públicas debido a su simplicidad, universalidad y amplio soporte de herramientas. La elección entre REST y sus alternativas depende de los requisitos específicos del proyecto: complejidad de las consultas, volumen de datos, necesidades de actualizaciones en tiempo real.