Introducción a las APIs RESTful

Guillermo Valdés (@guivaloz)

Octubre 2025

Analogía con restaurante

Analogía con restaurante

• Cliente: Persona que hace el pedido (navegador, app móvil, etc.)
• Pedido: Solicitud HTTP (GET, POST, PUT, DELETE)
• Mesero: Intermediario que lleva el pedido al restaurante y trae la comida (API)
• Servidor: Restaurante que recibe el pedido y lo prepara (servidor)
• Comida: Respuesta del servidor (datos en JSON, XML, etc.)

Definición de API

• API (Interfaz de Programación de Aplicaciones) es un conjunto de reglas y protocolos que permiten que diferentes aplicaciones se comuniquen entre sí.
• En el contexto de las APIs web, una API RESTful es un tipo de API que utiliza el protocolo HTTP para interactuar con recursos en un servidor.
• REST (Representational State Transfer) es un estilo arquitectónico que define un conjunto de restricciones para crear servicios web escalables y fáciles de mantener.

REST (Representational State Transfer)

Componentes de una solicitud API RESTful

• URL: La dirección del recurso al que se accede.
• Método HTTP: Define la acción a realizar (GET, POST, PUT, DELETE).
• Headers: Información adicional sobre la solicitud (autenticación, tipo de contenido, etc.).
• Body: Datos enviados al servidor

Partes de una URL

Métodos HTTP comunes

• GET: Recuperar datos de un recurso.
• POST: Crear un nuevo recurso.
• PUT: Actualizar un recurso existente.
• DELETE: Eliminar un recurso.
• PATCH: Actualizar parcialmente un recurso.

Headers (cabeceras)

La cabecera de una solicitud o respuesta contiene metadatos sobre la misma.

• Content-Type: Indica el tipo de contenido (application/json, text/html, etc.).
• Authorization: Contiene credenciales para autenticar al cliente.
• Language: Indica el idioma preferido para la respuesta.
• Device: Información sobre el dispositivo del cliente.

Body (cuerpo)

Cuando se envían datos al servidor (por ejemplo, en una solicitud POST o PUT), estos se incluyen en el cuerpo de la solicitud.

En el header se especifica el tipo de contenido, comúnmente JSON:

{
  "nombre": "Mario",
  "apellido_primero": "Moreno",
  "apodo": "Cantinflas"
}

JSON (JavaScript Object Notation)

JSON es un formato ligero de intercambio de datos, fácil de leer y escribir para humanos, y fácil de procesar y generar para máquinas.

Cómo es el formato JSON

• Texto plano.
• Estructura de pares clave-valor.
• Soporta tipos de datos como cadenas, números, booleanos, arreglos y objetos.
• Utiliza llaves {} para objetos y corchetes [] para arreglos.

Credenciales

Una API debería requerir credenciales para autenticar al cliente y autorizar el acceso a los recursos.

Las dos formas más comunes para autentificarse con una API son:

• API Key: Una clave única que identifica al cliente.
• OAuth: Un protocolo de autorización que permite a los usuarios compartir recursos sin compartir credenciales.

Cuida tu API Key

Credenciales en las solicitudes

Las credenciales se envían en cada solicitud, generalmente de dos maneras:

• Como parámetro en la URL:
  https://api.ejemplo.com/recursos?api_key=TU_API_KEY
• En el header de la solicitud:
  Authorization: Bearer TOKEN_DE_ACCESO

Componentes de una respuesta API RESTful

Una respuesta típica de una API RESTful incluye:

• Código de estado HTTP: Indica el resultado de la solicitud (200, 404, 500, etc.).
• Headers: Información adicional sobre la respuesta (tipo de contenido, longitud, etc.).
• Body: Datos devueltos por el servidor (generalmente en formato JSON o XML).

Códigos de estado HTTP comunes

• 200 OK: La solicitud fue exitosa.
• 401 Unauthorized: Credenciales inválidas o faltantes.
• 403 Forbidden: El cliente no tiene permiso para acceder al recurso.
• 404 Not Found: El recurso solicitado no existe.
• 500 Internal Server Error: Error en el servidor al procesar la solicitud.

HTTP.Cat

Matadatos en la cabecera de la respuesta

En el header de la respuesta puede haber información adicional, como:

• Content-Type: Indica el tipo de contenido devuelto (application/json, text/html, etc.).
• Content-Length: Indica la longitud del cuerpo de la respuesta.
• Server: Información sobre el servidor que procesó la solicitud.
• Date: Fecha y hora en que se generó la respuesta.
• Expires: Indica cuándo expira la respuesta.

Body de la respuesta

El cuerpo de la respuesta contiene los datos devueltos por el servidor.

Puede ser en varios formatos

• JSON (JavaScript Object Notation)
• XML (eXtensible Markup Language)
• Datos binarios (imágenes, archivos, etc.)

Ejemplo de respuesta JSON para un detalle

{
  "success": true,
  "message": "Usuario creado exitosamente",
  "data": {
    "id": 1,
    "nombre": "Mario",
    "apellido_primero": "Moreno",
    "apodo": "Cantinflas"
  }
}

Ejemplo de respuesta JSON para un listado

{
  "success": true,
  "message": "Apodos de los usuarios",
  "data": [
    { "id": 1, "apodo": "Cantinflas" },
    { "id": 2, "apodo": "El Charro Cantor" }
  ],
  "total": 2
}