API Fundamentals — Curso Interactivo

📘 Lección 1 de 12

¿Qué es una API?

Entiende el concepto fundamental que cambiará la forma en que construyes tus proyectos.

🎯 La analogía del restaurante

Imagina que estás en un restaurante. Tú (el cliente) quieres comer algo, pero no puedes entrar a la cocina. La cocina tiene toda la comida y sabe cómo prepararla, pero no puede atenderte directamente. Necesitas un intermediario.

👤

Cliente

Tu programa de gestión, una web, un bot, una app móvil...

→

🤵

Camarero (API)

Recibe pedidos, los traduce para la cocina y te trae la respuesta

→

👨‍🍳

Cocina

La base de datos, la lógica de negocio, los cálculos...

La API es ese camarero. Define qué puedes pedir (el menú), cómo pedirlo (la carta), y te trae la respuesta en un formato que entiendes.

💡 En términos técnicos

API significa Application Programming Interface (Interfaz de Programación de Aplicaciones). Es un conjunto de reglas que define cómo dos programas pueden comunicarse entre sí.

📌 Definición simple

Una API es una puerta de entrada controlada a tus datos y funcionalidades. Tú decides qué datos expones, quién puede acceder, y qué formato tienen las respuestas.

🔧 Ya usas APIs sin saberlo

En tu día a día ya trabajas con APIs constantemente:

✅ APIs que ya conoces

Cuando tu pool consulta el nodo chainweb para saber el último bloque → estás consumiendo la API del nodo
Cuando Frigate te devuelve los eventos detectados por las cámaras → lo hace a través de su API
Cuando configuras una cámara Dahua por HTTP → estás usando su API CGI
Cuando tu script PHP consulta la base de datos y devuelve datos → eso ya es media API

🔄 El problema que resuelve

Sin API, tu código mezcla todo: obtener datos, procesarlos y mostrarlos en HTML. Si mañana quieres mostrar esos mismos datos en un bot de Telegram, tienes que reescribir todo.

❌ SIN API (acoplado)

  Tu web PHP ──→ Base de datos ──→ HTML
  Si quieres un bot, reescribes todo
  Bot Telegram ──→ Base de datos ──→ Mensaje
  Si quieres una app, otra vez
  App móvil ──→ Base de datos ──→ Pantalla


✅ CON API (desacoplado)

  Base de datos
        ↓
    TU API  ← escribes la lógica UNA vez
        ↓
  ┌──────────────────────────┐
  │  Tu web        (consume)  │
  │  Bot Telegram  (consume)  │
  │  App móvil     (consume)  │
  │  Otro servicio (consume)  │
  └──────────────────────────┘

📐 Anatomía de una llamada API

Toda comunicación con una API tiene dos partes: la petición (request) y la respuesta (response).

              Petición (Request)
            

GET https://api.tupool.com/v1/stats
Headers:
  Authorization: Bearer tu-api-key-aqui
  Accept: application/json
            

              Respuesta (Response) — JSON
            

{
  "status": "ok",
  "data": {
    "miners": 45,
    "hashrate": "125 GH/s",
    "last_block": 4892710
  }
}
            

🧠 Conceptos clave de esta lección

⚠️ Recuerda estos términos

Cliente: quien hace la petición (tu web, un bot, una app...)
Servidor: quien recibe la petición y devuelve la respuesta (tu API)
Endpoint: la URL específica a la que llamas (como /v1/stats)
Request: la petición que envías
Response: la respuesta que recibes
JSON: el formato en que viajan los datos (lo veremos en la lección 3)

🔒

Completa la lectura para desbloquear el examen

🧪

Examen — Lección 1

1 ¿Cuál es la principal ventaja de usar una API frente a mezclar lógica y presentación en un mismo archivo PHP?

Es más rápido de programar la primera vez

Permite reutilizar la misma lógica desde múltiples interfaces sin reescribir código

Las APIs son obligatorias por ley europea

Solo las grandes empresas necesitan APIs

2 En la analogía del restaurante, ¿qué elemento representa la base de datos?

El cliente que pide la comida

El camarero

La cocina

El menú

3 Explica con tus propias palabras: ¿qué es un endpoint y pon un ejemplo práctico relacionado con tu trabajo en telecomunicaciones o minería?

Claude Corrección IA

📘 Lección 2 de 12

HTTP: El idioma de las APIs

Toda API web habla HTTP. Entender este protocolo es entender cómo viajan los datos por internet.

📡 ¿Qué es HTTP?

HTTP (HyperText Transfer Protocol) es el protocolo que usa todo internet para comunicarse. Cada vez que abres una web, tu navegador hace una petición HTTP al servidor y recibe una respuesta HTTP.

Las APIs funcionan exactamente igual. Tu programa envía una petición HTTP a una URL y recibe datos de vuelta. La diferencia es que en vez de recibir HTML (una página web), recibes JSON (datos puros).

📌 HTTP en tu mundo

Cuando accedes a una cámara Dahua por http://192.168.1.108/cgi-bin/snapshot.cgi, estás haciendo una petición HTTP. La cámara te responde con una imagen. Eso ya es una API.

📨 Anatomía de una petición HTTP

Toda petición HTTP tiene estas partes:

              Petición HTTP completa
            

── 1. MÉTODO + URL (qué quiero hacer y dónde) ──
GET /api/v1/pagos/pendientes HTTP/1.1

── 2. HEADERS (metadatos: quién soy, qué acepto) ──
Host: api.dnns.es
Authorization: Bearer sk-mi-api-key-secreta
Accept: application/json
Content-Type: application/json

── 3. BODY (datos que envío, solo en POST/PUT) ──
{
  "fecha_desde": "2026-01-01"
}
            

📬 Anatomía de una respuesta HTTP

              Respuesta HTTP
            

── 1. CÓDIGO DE ESTADO (¿fue bien?) ──
HTTP/1.1 200 OK

── 2. HEADERS DE RESPUESTA ──
Content-Type: application/json
X-Total-Count: 3

── 3. BODY (los datos que pediste) ──
{
  "pagos": [
    { "id": 1, "proveedor": "Suministros SL", "importe": 1850.00 },
    { "id": 2, "proveedor": "Cámaras Mallorca", "importe": 740.00 }
  ]
}
            

🚦 Códigos de estado HTTP

El servidor siempre responde con un código numérico que te dice qué pasó. Son como las señales de tráfico de las APIs:

2xx — Todo bien ✅

200 OK — La petición fue correcta, aquí tienes los datos
201 Created — Se creó un recurso nuevo (tras un POST)
204 No Content — Todo bien, pero no hay datos que devolver (tras un DELETE)

4xx — Error del cliente ⚠️

400 Bad Request — Tu petición tiene errores (faltan datos, formato incorrecto)
401 Unauthorized — No te has identificado (falta la API key)
403 Forbidden — Te has identificado pero no tienes permiso
404 Not Found — Esa URL no existe
429 Too Many Requests — Has hecho demasiadas peticiones, espera

5xx — Error del servidor 🔥

500 Internal Server Error — Algo falló en el servidor (bug en tu código)
502 Bad Gateway — El servidor intermedio no pudo conectar
503 Service Unavailable — El servidor está caído o en mantenimiento

🔑 Headers importantes

Los headers son como el sobre de una carta: contienen información sobre el mensaje pero no son el mensaje en sí.

🔖 Headers que usarás siempre

Content-Type: Dice qué formato tienen los datos que envías (application/json)
Accept: Dice qué formato esperas recibir
Authorization: Tu identificación (API key, token...)
User-Agent: Identifica quién hace la petición (tu app, tu script...)

🔒

Completa la lectura para desbloquear el examen

🧪

Examen — Lección 2

1 Si haces una petición a tu API y recibes un código 401, ¿qué significa y qué deberías comprobar?

La URL no existe, debo revisar la ruta del endpoint

No me he identificado, debo comprobar que envío la API key en el header Authorization

El servidor tiene un bug, debo revisar los logs

He hecho demasiadas peticiones, debo esperar

2 ¿Cuál es la diferencia entre un código 401 y un 403?

3 Cuando accedes a una cámara Dahua por HTTP para obtener un snapshot, identifica las partes de esa petición: método, URL/endpoint, y qué tipo de respuesta recibes.

Claude Corrección IA

📘 Lección 3 de 12

JSON: El formato de datos

JSON es el idioma universal en el que las APIs envían y reciben información.

📦 ¿Qué es JSON?

JSON (JavaScript Object Notation) es simplemente una forma de escribir datos de manera estructurada que tanto humanos como máquinas pueden leer fácilmente. Es como un formulario rellenado con datos.

Piensa en ello como una ficha técnica. Cuando haces una instalación de CCTV, rellenas una ficha con los datos: cliente, dirección, número de cámaras, modelo del grabador... JSON es exactamente eso, pero para que lo lean los programas.

📝 Estructura básica

              JSON — Tipos de datos
              
            

{
  "texto": "Esto es un string",
  "numero": 42,
  "decimal": 1850.50,
  "booleano": true,
  "nulo": null,
  "lista": ["uno", "dos", "tres"],
  "objeto": {
    "clave": "valor"
  }
}
            

🔧 JSON en tu mundo real

Así es como se vería la información de una instalación CCTV en formato JSON:

              JSON — Ejemplo instalación CCTV
              
            

{
  "instalacion": {
    "cliente": "Hotel Son Vida",
    "fecha": "2026-02-06",
    "ubicacion": "Palma de Mallorca",
    "camaras": [
      {
        "modelo": "Dahua IPC-HFW2831T-ZAS",
        "ip": "192.168.1.108",
        "ubicacion": "Entrada principal",
        "resolucion": "4K",
        "poe": true
      },
      {
        "modelo": "Dahua SD49425XB-HNR",
        "ip": "192.168.1.109",
        "ubicacion": "Parking",
        "resolucion": "4MP",
        "poe": true
      }
    ],
    "grabador": {
      "modelo": "Dahua NVR5216-16P-I",
      "canales": 16,
      "disco": "4TB"
    },
    "total_presupuesto": 3250.00
  }
}
            

✅ ¿Por qué JSON y no otro formato?

Legible: Puedes leerlo sin herramientas especiales
Universal: Todos los lenguajes lo entienden (PHP, JavaScript, Python...)
Ligero: Ocupa poco, viaja rápido por la red
Estándar: Es el formato que usan el 99% de las APIs del mundo

🐘 JSON en PHP

En PHP, trabajar con JSON es muy sencillo. Solo necesitas dos funciones:

              PHP — Convertir datos a JSON y viceversa
              
            

// Convertir un array PHP a JSON (para ENVIAR respuestas)
$datos = [
    'miners' => 45,
    'hashrate' => '125 GH/s',
    'activo' => true
];
$json = json_encode($datos);
// Resultado: {"miners":45,"hashrate":"125 GH/s","activo":true}

// Convertir JSON a array PHP (para RECIBIR peticiones)
$json_recibido = '{"proveedor":"Cables SL","importe":450}';
$datos = json_decode($json_recibido, true);
// Ahora: $datos['proveedor'] = "Cables SL"
//        $datos['importe'] = 450
            

🔒

Completa la lectura para desbloquear el examen

🧪

Examen — Lección 3

1 ¿Qué función de PHP usarías para convertir un array PHP en un string JSON que puedas enviar como respuesta de tu API?

json_decode()

json_encode()

serialize()

array_to_json()

💡 En términos técnicos

🔧 Ya usas APIs sin saberlo

🔄 El problema que resuelve

📐 Anatomía de una llamada API

🧠 Conceptos clave de esta lección

Examen — Lección 1

HTTP: El idioma de las APIs

📡 ¿Qué es HTTP?

📨 Anatomía de una petición HTTP

📬 Anatomía de una respuesta HTTP

🚦 Códigos de estado HTTP

🔑 Headers importantes

Examen — Lección 2

JSON: El formato de datos

📦 ¿Qué es JSON?

📝 Estructura básica

🔧 JSON en tu mundo real

🐘 JSON en PHP

Examen — Lección 3

Endpoints y rutas

Métodos: GET, POST, PUT, DELETE

Tu primera API en PHP

Autenticación y API Keys

Manejo de errores

Conectando con base de datos

Diseñando tu API de pagos

Sistema de conectores

Generador SEPA XML

Conexión con Claude