Capítulo 1.4: Estructura de la API REST

Tiempo de estudio: 45 minutos

---

1. API REST: Arquitectura de una estación espacial

Imagina una estación espacial donde cada módulo tiene:

• Puerto de acoplamiento estándar (interfaz única)

• Especialización clara (módulo de vivienda, laboratorio, almacén)

• Sistema de coordenadas (ubicación precisa)

La API REST (Representational State Transfer) funciona bajo los mismos principios:

• Interfaz única para todos los recursos

• Separación clara de componentes

• Direccionamiento a través de URI (coordenadas espaciales)

💡 Idea clave:

Cada recurso (planetas, cohetes, astronautas) tiene una URL única e interactúa a través de métodos HTTP.

---

2. 6 principios REST en la analogía espacial

Principio REST	Análogo en la ISS	Significado para la API
Interfaz uniforme	Nodos de acoplamiento estándar	Mismas reglas para todas las solicitudes
Sin estado	Cada comando es autosuficiente	El servidor no almacena el estado del cliente
Almacenamiento en caché	Reservas locales de provisiones	Almacenamiento de respuestas frecuentes
Cliente-servidor	Clara separación: Centro de Control ↔ Estación	Desarrollo independiente de componentes
Sistema en capas	Satélites repetidores	Proxies, equilibradores de carga
Código bajo demanda	Descarga de software para experimentos	(Opcional) Transferencia de scripts

---

3. Recursos y URI: Coordenadas espaciales

Cada objeto en la API es un recurso con una dirección única:

https://api.spacexdata.com/v4/    ← URL base
          rockets/            ← Colección de cohetes
          rockets/5e9d0d95eda69973a809d1ec ← Cohete específico (por ID)

Ejemplos de recursos espaciales:

• GET /stars → Lista de estrellas
• GET /stars/sirius → Datos sobre Sirio
• POST /satellites → Lanzar un nuevo satélite
• PUT /missions/artemis → Actualizar misión

Esquema de jerarquía URI:

[URL base]
├── /planets          → Colección de planetas
│   ├── /mars         → Recurso "Marte"
│   └── /venus        → Recurso "Venus"
└── /launches         → Colección de lanzamientos
    ├── /upcoming     → Subcolección
    └── /latest       → Recurso

---

4. Operaciones CRUD a través de métodos HTTP

Operación	Método HTTP	Ejemplo (Estación espacial)	Respuesta del servidor
Crear	POST	Enviar nuevo módulo	201 Created
Leer	GET	Solicitar datos sobre un módulo	200 OK
Actualizar	PUT	Reconfigurar módulo	200 OK
Eliminar	DELETE	Desacoplar módulo antiguo	204 No Content

⚡ Ejemplo de código (Adición de un satélite):

import requests

# Usamos un servicio de prueba que simula la creación de un recurso
new_post = {
    "title": "New Telescope Launch",
    "body": "Hubble-2 is ready for deployment.",
    "userId": 1
}

# Clave API condicional para demostrar los encabezados
headers = {
    "Authorization": "Bearer YOUR_DEMO_KEY",
    "Content-Type": "application/json; charset=UTF-8"
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    headers=headers
)

if response.status_code == 201:
    print("✅ ¡Publicación sobre el nuevo satélite creada con éxito!")
    print("Respuesta del servidor:")
    print(response.json())
else:
    print(f"❌ ¡Error! Estado: {response.status_code}")

---

5. Versionado de API: Evolución de la estación

Así como la ISS se actualiza (Módulo "Zarya" → "Nauka"), la API cambia de versión:

• En la URL: https://api.spacex.com/v4/rockets
• En los encabezados: Accept: application/vnd.spacex-v5+json

Por qué es importante:

• v1: Funcionalidad básica
• v2: Campos nuevos añadidos
• v3: Estructura de respuestas modificada

⚠️ Consejo: ¡Siempre especifica la versión en las solicitudes, de lo contrario el "acoplamiento" podría fallar!

---

6. Hipermedia (HATEOAS): Navegación en el espacio

La respuesta de la API contiene enlaces a recursos relacionados, como un mapa de la estación:

{
  "id": "iss",
  "name": "Estación Espacial Internacional",
  "crew": 7,
  "_links": {
    "self": { "href": "/stations/iss" },
    "modules": { "href": "/stations/iss/modules" },
    "schedule": { "href": "/stations/iss/schedule" }
  }
}

---

Cuestionario de repaso

1. REST se expande como:

a) Rocket Engine System Transfer b) Representational State Transfer c) Remote Space Technology

2. El principio "Stateless" significa:

a) El servidor almacena el historial de solicitudes b) Cada solicitud es autosuficiente c) Los datos se transmiten solo a través de SSL

3. URI para obtener datos sobre el cohete Falcon Heavy:

a) POST /rockets/falcon-heavy b) GET /falcon-heavy c) GET /rockets/falcon-heavy

4. Método para la actualización completa de un recurso:

a) PATCH b) POST c) PUT

5. HATEOAS en una API es:

a) Un sistema de enlaces a recursos relacionados b) Un protocolo de cifrado c) Un lenguaje de consulta

Verificar

---

🚀 Resumen del capítulo:

La API REST es una "arquitectura de estación espacial" estandarizada para servicios web. Recuerda:

• Recursos = Objetos (cohetes, planetas)
• URI = Coordenadas de los objetos
• Métodos HTTP = Comandos de control
• Versiones = Modernizaciones de la estación

¡Final de la preparación! En el próximo capítulo, lanzaremos una "sonda de prueba" — aprenderemos a probar API a través de Postman.

📌 Práctica: Explora la estructura de la API de SpaceX e intenta ejecutar:

GET https://api.spacexdata.com/v4/launches/latest — ¡observa el URI y la estructura JSON!