Módulo 2: REST Principles

Introducción al Módulo 2: REST Principles

Siguiente →

Descripción

En el Módulo 1 aprendiste el protocolo HTTP: requests, responses, métodos, status codes, headers. Sabes cómo enviar una petición y leer la respuesta. Pero HTTP solo te da el cómo — no te dice cómo organizar las URLs, cuándo usar cada método, ni qué estructura darle a tu API para que otros developers la entiendan sin leer documentación.

REST (Representational State Transfer) es la arquitectura que resuelve eso. REST toma HTTP y le da significado: los recursos son sustantivos (/users, /products), los métodos son verbos (GET = leer, POST = crear), y las URLs siguen patrones predecibles. Cuando una API sigue REST, cualquier developer puede inferir cómo usarla: "si existe /users, seguro /users/1 me da el usuario con ID 1."

Este módulo te enseña a pensar en REST. Al terminar, vas a poder evaluar si una API está bien diseñada, consumirla siguiendo sus convenciones, y diseñar tus propios endpoints para cuando construyas APIs con FastAPI. La diferencia entre un developer que "hace requests" y uno que "entiende APIs" es exactamente lo que cubre este módulo.

¿Dónde estamos en la guía?

Contexto en la guía

Módulo 1: HTTP Protocol Fundamentals ✅ Completado
    Aprendiste: requests, responses, métodos, status codes, headers
    ↓
Módulo 2: REST Principles ← Estás aquí
    Aprenderás: recursos, URIs, CRUD, diseño de APIs
    ↓
Módulo 3: JSON & Tools
    Aprenderás: serialización, validación, Postman
    ↓
Módulo 4: Consumir APIs Públicas (Proyecto Integrador)
    Construirás: REST Client CLI con 5+ APIs

Progresión dentro de la guía

Módulo 1: Entender el PROTOCOLO          → HTTP (la infraestructura)
Módulo 2: Aprender las CONVENCIONES      → REST (la arquitectura) ← ESTÁS AQUÍ
Módulo 3: Dominar el FORMATO Y HERRAMIENTAS → JSON + Postman (el ecosistema)
Módulo 4: INTEGRAR todo en un proyecto   → REST Client CLI (la práctica)

Conexión con el Módulo 1

La transición del Módulo 1 al 2 es directa: "ya sabes el protocolo a bajo nivel → ahora aprende las convenciones que hacen las APIs predecibles y profesionales."

Lo que aprendiste en M1Cómo se usa en M2
Métodos HTTP (GET, POST, PUT, DELETE)Se mapean a operaciones CRUD sobre recursos
Status codes (200, 201, 404, 500)Se usan consistentemente según la operación REST
Headers (Content-Type, Accept)Definen el contrato de formato entre cliente y servidor
URLs y pathsSe convierten en URIs que representan recursos
Request/Response cycleSe estructura en patrones predecibles y repetibles

El Módulo 1 te dio las piezas. El Módulo 2 te enseña cómo ensamblarlas para que formen algo coherente.

El Salto: De "Hacer Requests" a "Entender APIs"

Sin REST: HTTP como herramienta genérica

Imagina que consumes una API sin convenciones REST. Los endpoints se ven así:

POST /api/getUsers              → Obtener lista de usuarios
POST /api/getUserById            → Obtener un usuario (ID en el body)
POST /api/createNewUser          → Crear usuario
POST /api/updateUserInformation  → Actualizar usuario
POST /api/removeUser             → Eliminar usuario

Todo es POST. Los nombres de los endpoints son verbos largos. Para saber qué hace cada uno, necesitas leer la documentación completa. Y cada API nueva que consumas tiene una estructura diferente — no hay patrones, no hay predictibilidad, no hay forma de inferir nada.

Esto no es hipotético. APIs así existen (muchas APIs legacy funcionan exactamente así). Y consumirlas es lento y frustrante porque cada endpoint es una sorpresa.

Con REST: HTTP con significado

La misma API, diseñada con principios REST:

GET    /users          → Obtener lista de usuarios
GET    /users/42       → Obtener usuario con ID 42
POST   /users          → Crear nuevo usuario
PUT    /users/42       → Actualizar usuario completo
PATCH  /users/42       → Actualizar campos específicos
DELETE /users/42       → Eliminar usuario

Sin leer documentación, un developer que conoce REST puede inferir:

  • "Si hay /users, probablemente hay /users/{id} para un usuario específico."
  • "GET para leer, POST para crear, PUT/PATCH para actualizar, DELETE para eliminar."
  • "Si necesito los posts de un usuario, probablemente es /users/42/posts."

Esa capacidad de inferir la estructura de una API sin documentación es lo que REST te da. Y es la razón por la que el 90% de las APIs modernas (GitHub, Stripe, Twitter, OpenAI) siguen REST.

La diferencia en velocidad

Sin REST:
1. Recibir documentación de la API         → 10 minutos
2. Leer todos los endpoints                → 20 minutos
3. Entender la estructura de cada request  → 15 minutos
4. Empezar a consumir                      → 45 minutos después
5. Cada API nueva: repetir desde el paso 1

Con REST:
1. Ver el base URL y un endpoint           → 1 minuto
2. Inferir el resto de los endpoints       → 2 minutos
3. Verificar con 2-3 requests de prueba    → 3 minutos
4. Empezar a consumir                      → 6 minutos después
5. Cada API nueva REST: mismos patrones

REST no es solo una convención elegante — es una inversión de tiempo que se paga en cada API que consumes después de aprenderlo.

Vista Previa: REST en Acción

Aquí tienes un ejemplo concreto de cómo se ven los principios REST aplicados a un dominio real. Supón que estás diseñando una API para un sistema de tareas (todo app):

Los recursos

Recurso principal: Task (tarea)
Recurso secundario: Category (categoría)
Relación: cada Task pertenece a una Category

Los endpoints REST

Tareas:
GET    /tasks              → Listar todas las tareas
GET    /tasks/7            → Obtener tarea con ID 7
POST   /tasks              → Crear nueva tarea
PUT    /tasks/7            → Actualizar tarea completa
PATCH  /tasks/7            → Marcar como completada (solo un campo)
DELETE /tasks/7            → Eliminar tarea

Categorías:
GET    /categories         → Listar categorías
GET    /categories/3       → Obtener categoría 3
POST   /categories         → Crear categoría

Relaciones:
GET    /categories/3/tasks → Tareas de la categoría 3

Filtros y paginación:
GET    /tasks?status=pending          → Tareas pendientes
GET    /tasks?category_id=3&sort=date → Tareas de categoría 3, ordenadas por fecha
GET    /tasks?page=2&per_page=10      → Página 2, 10 por página

En Python

import requests

BASE = "https://api.example.com/v1"

tasks = requests.get(f"{BASE}/tasks").json()

new_task = requests.post(f"{BASE}/tasks", json={
    "title": "Aprender REST",
    "category_id": 3
}).json()

requests.patch(f"{BASE}/tasks/{new_task['id']}", json={
    "completed": True
})

pending = requests.get(f"{BASE}/tasks", params={
    "status": "pending",
    "sort": "created_at"
}).json()

Los patrones son predecibles, consistentes, y reutilizables. Eso es REST.

Objetivo del módulo

Al completar este módulo, serás capaz de:

  • ✅ Identificar recursos en cualquier dominio (users, orders, products, posts)
  • ✅ Diseñar URIs RESTful: sustantivos plurales, IDs en path, sin verbos en URL
  • ✅ Mapear operaciones CRUD a métodos HTTP correctamente
  • ✅ Entender idempotencia y statelessness — y por qué importan
  • ✅ Aplicar versioning de APIs (URL vs header)
  • ✅ Diseñar paginación y filtrado
  • ✅ Evaluar si una API real sigue buenas prácticas REST
  • ✅ Crear un documento de diseño de API REST para un dominio

Objetivo profesional

Después de este módulo, cuando te presenten una API nueva, tu primer pensamiento será "¿qué recursos expone?" y "¿qué operaciones soporta?" — no "¿dónde está la documentación?". Esa mentalidad de recursos es lo que distingue a un developer que consume APIs con confianza de uno que las usa con miedo.

Prerequisitos

Conocimiento requerido

  • Módulo 1 completado: entender requests, responses, métodos HTTP (GET, POST, PUT, PATCH, DELETE), status codes, headers
  • Python con requests: saber hacer peticiones HTTP con la library requests
  • JSON básico: leer y manipular objetos JSON

Verificación rápida

Responde estas preguntas:

  1. ¿Puedes explicar la diferencia entre GET y POST?
  2. ¿Sabes qué significa un status code 404? ¿Y un 201?
  3. ¿Puedes hacer un requests.get() con headers personalizados?

Si respondiste "sí" a las 3, estás listo. Si alguna te genera duda, revisita las cápsulas correspondientes del Módulo 1.

Setup técnico

Reutiliza el entorno del Módulo 1:

# Activa tu entorno virtual
cd rest-apis-guide
source venv/bin/activate  # Mac/Linux

# Verifica que requests funciona
python -c "import requests; print('requests OK')"

# Crea carpeta para este módulo
mkdir -p modulo-02

No necesitas instalar nada nuevo para este módulo. Los ejercicios usan requests (que ya tienes) y APIs públicas.

APIs que usarás en los ejercicios

APIURL BaseAuth
JSONPlaceholderhttps://jsonplaceholder.typicode.comSin auth
GitHub APIhttps://api.github.comToken opcional
Dog CEOhttps://dog.ceo/apiSin auth

Estas APIs son gratuitas y no requieren registro (GitHub funciona sin token para endpoints públicos).

Roadmap del módulo

CápsulaTemaQué aprenderás
01Introducción al móduloContexto, objetivos, roadmap ← Estás aquí
02Recursos y URIsRecursos como sustantivos, diseño de URLs predecibles
03CRUD y Métodos HTTPMapping de operaciones CRUD a métodos HTTP
04Idempotencia y StatelessnessPropiedades clave de REST y por qué importan
05Diseño de APIsNaming conventions, buenas y malas prácticas
06Versionado y PaginaciónVersioning, pagination, filtering, sorting
07APIs Reales: AnálisisEvaluar GitHub, JSONPlaceholder y OpenWeather como APIs REST
08Proyecto: REST API Design DocDiseñar los endpoints de una API completa

Flujo de aprendizaje

Recursos y URIs (02)
  "¿Qué son los recursos? ¿Cómo diseño URLs?"
    ↓
CRUD + Métodos (03) + Idempotencia (04)
  "¿Qué operaciones existen? ¿Qué propiedades tienen?"
    ↓
Diseño de APIs (05) + Versionado/Paginación (06)
  "¿Cómo diseño una API profesional?"
    ↓
APIs Reales (07) + Proyecto (08)
  "¿Cómo aplican estos principios las APIs de verdad?"

Primero entiendes los conceptos (recursos, CRUD, propiedades), luego aplicas las convenciones de diseño, y al final analizas APIs reales y diseñas la tuya.

Duración estimada del módulo: 4-5 horas (lecturas + ejercicios + proyecto).

Analogía: REST como el sistema de una biblioteca

Si REST te parece abstracto, piensa en una biblioteca:

BIBLIOTECA                          API REST
───────────                         ────────
Recursos = libros, autores,         Recursos = users, products,
           miembros, préstamos                 orders, reviews

Organización:                       URIs:
  Sección → Estante → Libro           /authors → /authors/42 → /authors/42/books

Operaciones:                        Métodos HTTP:
  Consultar catálogo = leer           GET = leer
  Registrar libro nuevo = crear       POST = crear
  Actualizar datos = modificar        PUT/PATCH = actualizar
  Dar de baja = eliminar              DELETE = eliminar

Reglas:                             Principios REST:
  Cada libro tiene un código único    Cada recurso tiene un ID único
  El código no cambia                 La URI es estable
  Consultar no modifica nada          GET es idempotente y safe
  El catálogo está organizado         Las URIs son predecibles

Una biblioteca bien organizada te permite encontrar cualquier libro en minutos, incluso sin ayuda del bibliotecario. Una API REST bien diseñada te permite consumirla en minutos, incluso sin documentación detallada. La organización predecible es el valor fundamental de REST.

Conexión con el proyecto de la guía

El REST Client CLI del Módulo 4 consume APIs que siguen REST: JSONPlaceholder (/posts, /users, /comments), GitHub (/repos, /users), OpenWeather. Sin entender REST, tu CLI sería código que funciona por casualidad. Con REST, puedes:

  • Predecir endpoints sin documentación (/users/1/posts → posts del usuario 1)
  • Usar el método correcto para cada operación (GET para leer, POST para crear)
  • Manejar paginación (?page=2&per_page=10) en APIs que devuelven muchos resultados
  • Interpretar responses basándote en convenciones, no en ensayo y error

El proyecto del módulo: REST API Design Doc

En la cápsula 08, elegirás un dominio (tienda online, red social, sistema de reservas) y diseñarás todos sus endpoints REST: recursos, URIs, métodos, request bodies, response formats, status codes, paginación y versionado. Es un ejercicio de diseño, no de código — y es exactamente lo que harás antes de construir una API real con FastAPI.

Qué NO cubre este módulo

  • ❌ Construir APIs — Este módulo es sobre principios y diseño. Construir APIs con código es la guía FastAPI Fundamentals (#6).
  • ❌ GraphQL, gRPC, WebSockets — Son alternativas a REST, no se cubren en esta guía fundacional.
  • ❌ Autenticación avanzada — OAuth2, JWT en profundidad se cubren más adelante en el path.
  • ❌ HATEOAS en profundidad — Lo mencionamos como concepto, pero no es común en la práctica y no lo necesitas ahora.
  • ❌ OpenAPI/Swagger — Herramientas de documentación de APIs se verán en la guía de FastAPI.

REST no es dogma

Un punto importante antes de empezar: REST tiene principios, no leyes absolutas. Vas a encontrar APIs que no siguen REST al 100% — y eso está bien. Algunas APIs usan POST para todo, otras ponen verbos en la URL, otras no versionan.

Tu trabajo no es ser purista. Tu trabajo es:

  1. Conocer las convenciones para que puedas aplicarlas cuando diseñes
  2. Reconocer los patrones para que puedas consumir cualquier API rápido
  3. Adaptarte cuando una API no siga los principios al pie de la letra

Las cápsulas de este módulo te dan los principios Y te muestran cómo la industria los aplica (o no) en la práctica.

Troubleshooting

"¿REST es un estándar o una convención?"

REST es un estilo arquitectónico, no un estándar formal como HTTP o SQL. No hay un "comité REST" que apruebe o rechace APIs. Hay principios documentados por Roy Fielding en su tesis doctoral (2000), y la industria los adoptó como convenciones. Esto significa que hay flexibilidad — pero también significa que cada equipo puede interpretar REST diferente.

"¿Todas las APIs son REST?"

No. Existen APIs SOAP (XML-based, comunes en enterprise legacy), GraphQL (query language de Facebook), gRPC (Protocol Buffers de Google), y APIs RPC genéricas. Pero REST domina el ecosistema web actual. GitHub, Stripe, Twilio, OpenAI — todas usan REST. Aprender REST primero te cubre el 90% de las APIs que vas a consumir.

"¿REST y RESTful son lo mismo?"

Técnicamente, "REST" es la arquitectura y "RESTful" es el adjetivo para describir APIs que siguen esa arquitectura. En la práctica, se usan indistintamente. Cuando alguien dice "API REST" o "API RESTful", se refiere a lo mismo.

"¿Puedo diseñar una buena API sin saber REST?"

Puedes, pero reinventarás la rueda. REST te da convenciones probadas por 20+ años de uso masivo. Sin REST, cada decisión de diseño (¿cómo nombro los endpoints? ¿qué métodos uso? ¿cómo pagino?) la tomas desde cero. Con REST, la mayoría de esas decisiones ya están resueltas.

"¿Por qué importa la idempotencia si solo voy a consumir APIs?"

Porque afecta cómo manejas retries. Si una petición falla y necesitas reenviarla, necesitas saber si es seguro hacerlo. Un GET es idempotente — puedes reenviarlo sin consecuencias. Un POST no lo es — reenviarlo podría crear un recurso duplicado. Esa distinción te evita bugs sutiles.

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes identificar los recursos de un dominio (ej: "una tienda online tiene users, products, orders, reviews")
  • ✅ Puedes diseñar URIs RESTful para esos recursos (/products/42/reviews)
  • ✅ Puedes explicar por qué /getUsers es mala práctica y /users es correcta
  • ✅ Puedes mapear CRUD a HTTP methods sin dudar
  • ✅ Puedes analizar una API real y evaluar qué tan bien sigue REST
  • ✅ Tu documento de diseño de API tiene endpoints claros, consistentes y predecibles

Test rápido de autoevaluación

Al terminar el módulo, deberías poder responder:

  1. ¿Qué es un recurso en REST? Da 3 ejemplos de tu dominio favorito.
  2. ¿Cuál es la URI correcta para obtener el post #5 del usuario #42?
  3. ¿Qué método HTTP usarías para cambiar solo el email de un usuario?
  4. ¿Qué significa que GET sea idempotente y safe?
  5. ¿Por qué una API stateless es más escalable que una stateful?
  6. ¿Qué diferencia hay entre versionado por URL (/v2/users) y por header?

Si puedes responder las 6 con confianza, dominaste REST.

Resumen

  • REST es la arquitectura que le da estructura a HTTP — recursos como sustantivos, métodos como verbos
  • La capacidad de inferir la estructura de una API sin documentación es lo que REST te da
  • Este módulo convierte "sé hacer requests" en "sé diseñar y consumir APIs profesionales"
  • Aprenderás recursos, URIs, CRUD, idempotencia, statelessness, versionado, paginación
  • Todo se aplica directamente en el REST Client CLI del Módulo 4
  • REST tiene principios, no leyes — el pragmatismo importa más que el purismo
  • El proyecto final del módulo es un documento de diseño de API REST completo

Recursos adicionales

Si quieres contexto antes de empezar (opcional):

  1. REST API Tutorial - Referencia completa de principios REST
  2. MDN: An Overview of HTTP - Repaso de HTTP (base de REST)
  3. Roy Fielding's Dissertation (Chapter 5) - El paper original que definió REST
  4. GitHub REST API Documentation - Ejemplo de API REST bien documentada
  5. JSONPlaceholder - API REST de pruebas que usarás en ejercicios
  6. Best Practices for REST API Design - Artículo práctico de Stack Overflow

Siguiente cápsula: Recursos y URIs — vas a aprender a pensar en términos de recursos (sustantivos) y diseñar URLs predecibles que cualquier developer pueda entender.

← AnteriorProyecto del Módulo 1: HTTP ExplorerSiguiente →Recursos y URIs: El Vocabulario de REST