¿Qué es una API REST?

Una API REST es una API que sigue el estilo arquitectónico REST: recursos en URLs, solicitudes sin estado y métodos HTTP estándar. REST — Representational State Transfer, definido en la tesis doctoral de Roy Fielding del año 2000 — es un estilo, no un protocolo ni un estándar: un conjunto de restricciones que, honradas en conjunto, producen APIs que toda la web ya sabe consumir, cachear y escalar.

Puntos clave

Un ciclo CRUD completo en HTTP crudo

Todo el estilo en cuatro solicitudes — esto es lo que cada framework y SDK termina enviando:

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

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

PUT /v1/posts/8fk2                 →  200 OK                 reemplazar
{ "title": "Hello again" }            (PATCH actualizaría campos)

DELETE /v1/posts/8fk2              →  204 No Content         eliminar
GET /v1/posts/8fk2                 →  404 Not Found          …y ya no está

El mismo ciclo a través de SDKs que envuelven las llamadas 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

Las seis restricciones de REST

1. Cliente-servidor — interfaz e implementación evolucionan de forma independiente; la UI nunca sabe cómo funciona el almacenamiento.
2. Sin estado — cada solicitud es autocontenida; el servidor no guarda sesión entre llamadas, que es lo que permite que cualquier réplica responda cualquier request.
3. Cacheable — las respuestas declaran su propia cacheabilidad; los GET con headers de caché correctos ponen toda la infraestructura de caché de la web (navegadores, CDNs, proxies) a trabajar para tu API.
4. Interfaz uniforme — la restricción que es REST, en cuatro partes: recursos identificados por URIs; manipulación mediante representaciones (envías de vuelta el JSON en el que quieres que el recurso se convierta); mensajes autodescriptivos (método + headers dicen todo lo necesario para procesar la solicitud); e hipermedia como motor del estado de la aplicación (las respuestas enlazan las siguientes acciones).
5. Sistema en capas — los clientes no pueden saber si hablan con el origen, un caché o un gateway; los intermediarios se insertan con libertad.
6. Código bajo demanda (opcional) — los servidores pueden enviar código ejecutable a los clientes; la única restricción marcada como opcional, y la que la mayoría de las APIs ignora.

Métodos HTTP: seguridad, idempotencia, CRUD

La tabla que falta en casi toda página de ranking — la semántica del RFC 9110, condensada:

Seguro significa que la solicitud no cambia nada; idempotente, que repetirla no cambia nada más. Esto no es trivia — es la política de reintentos: un timeout de red en un PUT se puede reintentar sin miedo; el mismo timeout en un POST necesita una idempotency key o un chequeo de duplicados. El mapeo CRUD completo tiene su propia entrada.

Códigos de estado: qué devolver y cuándo

Las distinciones 401/403 y 200/201/204 son donde se nota la artesanía de una API: los códigos precisos hacen que los clientes puedan depurarse con nada más que la línea de estado.

¿Tu API es realmente REST? La escalera de madurez

La sección honesta que los explicadores comerciales omiten. El Richardson Maturity Model califica las APIs HTTP: nivel 0 (una URL, un verbo, RPC disfrazado), nivel 1 (recursos en URLs), nivel 2 (métodos y códigos de estado correctos), nivel 3 (hipermedia — HATEOAS).

Por insistencia del propio Fielding, una API sin hipermedia no es REST — escribió un ensayo punzante diciendo exactamente eso. En la práctica, casi toda “API REST” aclamada es una API HTTP de nivel 2: recursos, verbos, códigos de estado, JSON, sin hipermedia. Esto importa menos como pureza y más como vocabulario — conocer la escalera te dice qué significa el término en una oferta de trabajo (nivel 2) versus en la tesis (nivel 3), y te salva tanto del HATEOAS de culto al cargamento como de las correcciones pedantes.

REST vs. SOAP vs. GraphQL vs. gRPC

La comparación con GraphQL tiene una entrada completa propia.

Convenciones que hacen agradable una API REST

Más allá de las restricciones, las convenciones con las que los consumidores te califican en silencio: recursos con sustantivos en plural (/posts, no /getPost); anidar un nivel como máximo (/posts/8fk2/comments, y ahí parar); paginación en cada colección — basada en cursores por profundidad y estabilidad, con límites aplicados; filtrado y ordenamiento como parámetros de query, no como variantes del endpoint; versionado con una política explícita (path /v1/ o header — elige uno, publica ventanas de deprecación); negociación de contenido respetada (Accept, Content-Type); y errores como JSON estructurado con un código legible por máquinas, no solo prosa. Nada de esto está en la tesis; todo está en la diferencia entre una API que los desarrolladores recomiendan y una que soportan.

Casos de uso comunes

• APIs públicas y de socios — la ubicuidad de REST es la funcionalidad: cada lenguaje, herramienta y desarrollador lo habla.
• Backends de apps móviles y web — el CRUD de recursos sobre HTTP calza con cómo la mayoría de las pantallas consume datos en realidad.
• Costuras entre microservicios — contratos internos donde el tooling de HTTP (gateways, tracing, caché) se gana su lugar.
• Integraciones estilo webhook — sistemas notificando a sistemas con llamadas HTTP simples que ambos lados ya entienden.
• APIs de datos autogeneradas — plataformas que exponen una base de datos como recursos REST — la ruta más rápida del esquema a una API funcionando.

¿Deberías usar REST? Matriz de decisión

Limitaciones y trade-offs

• Las representaciones fijas no les quedan a clientes diversos. El par overfetching/underfetching es la debilidad estructural de REST; los sparse fieldsets y los parámetros de expansión mitigan, GraphQL rediseña.
• No hay contrato obligatorio. Nada fuerza una spec OpenAPI, así que muchas APIs REST están documentadas por folklore; la disciplina es opcional donde gRPC y GraphQL la hacen estructural.
• La ausencia de estado repite contexto. La auth y el contexto de tenant viajan en cada solicitud — barato en bytes, pero empuja la semántica de sesión a los tokens y vuelve incómodos algunos flujos (transacciones de varios pasos).
• La tentación del N+1 por diseño. Pensar en recurso-por-URL invita a clientes de una-llamada-por-ítem; las buenas APIs entregan expansión y batch antes de que los consumidores improvisen loops.
• La palabra “REST” es ambigua. API HTTP de nivel 2 en la mayoría de las bocas, arquitectura de hipermedia en la tesis — lee cuál de las dos quiere decir una spec, una oferta de trabajo o un revisor antes de discutir.

APIs REST en Back4app

Back4app es una plataforma open-source de Backend as a Service (BaaS) que combina base de datos gestionada, APIs REST y GraphQL generadas automáticamente, autenticación, almacenamiento de archivos y funciones serverless con Cloud Code. La API REST aquí se genera, no se construye: cada clase de tu modelo de datos es de inmediato un recurso — POST /classes/Post crea, GET /classes/Post/:id lee, con los métodos, los códigos de estado y la semántica de Location del recorrido de arriba — detrás de keys, tokens de usuario y permisos a nivel de clase haciendo cumplir la frontera. Los code tabs muestran el mismo ciclo a través de los SDKs, que son envoltorios idiomáticos delgados sobre exactamente este HTTP; cuando una operación crece más allá del CRUD, una función de Cloud Code agrega un endpoint personalizado en un archivo. REST de nivel 2, correcto por defecto, del esquema a la URL en lo que tardas en definir la clase.