Que es una API REST y como funciona: guia para principiantes

Introduccion

Si alguna vez te has preguntado como tu aplicacion del clima obtiene datos actualizados, como una tienda online procesa tus pagos o como diferentes servicios de software se comunican entre si, la respuesta en la mayoria de los casos es: a traves de una API REST. Las APIs son el pegamento invisible que conecta el mundo digital moderno.

En este articulo, vamos a explicar desde cero que es una API REST, como funciona y como puedes empezar a consumir APIs con ejemplos practicos de codigo. No necesitas experiencia previa en desarrollo web; solo necesitas curiosidad y ganas de aprender.

Que es una API

API son las siglas de Application Programming Interface (Interfaz de Programacion de Aplicaciones). En terminos simples, una API es un conjunto de reglas y definiciones que permite que dos aplicaciones se comuniquen entre si. Es como un mesero en un restaurante: tu (la aplicacion cliente) le dices al mesero (la API) lo que quieres, el mesero lleva tu pedido a la cocina (el servidor) y te trae de vuelta lo que pediste.

Las APIs definen que operaciones estan disponibles, que datos necesitas enviar para cada operacion y que datos recibiras como respuesta. Esto permite que los desarrolladores integren funcionalidades de otros servicios en sus propias aplicaciones sin necesidad de entender como funcionan internamente esos servicios.

Que es REST

REST (Representational State Transfer) es un estilo de arquitectura para disenar APIs que se comunican a traves del protocolo HTTP, el mismo protocolo que usa tu navegador para cargar paginas web. REST no es un estandar estricto ni un protocolo, sino un conjunto de principios y restricciones que, cuando se siguen, producen APIs predecibles, escalables y faciles de usar.

Principios de REST

Los principios fundamentales de REST incluyen la arquitectura cliente-servidor (el cliente y el servidor son independientes), la comunicacion sin estado (cada solicitud contiene toda la informacion necesaria para ser procesada, sin depender de solicitudes anteriores), la capacidad de cache (las respuestas pueden ser almacenadas en cache para mejorar el rendimiento), una interfaz uniforme (las URLs y metodos HTTP se usan de forma consistente) y un sistema de capas (el cliente no necesita saber si se comunica directamente con el servidor o a traves de intermediarios).

Metodos HTTP: las acciones de una API REST

Los metodos HTTP definen que tipo de operacion quieres realizar sobre un recurso. Piensa en los recursos como los "sustantivos" (usuarios, productos, pedidos) y los metodos HTTP como los "verbos" (obtener, crear, actualizar, eliminar). Los cuatro metodos principales son:

GET - Obtener datos

El metodo GET se usa para solicitar datos del servidor. Es una operacion de solo lectura que no modifica nada en el servidor. Ejemplos: obtener la lista de todos los usuarios, obtener los detalles de un producto especifico, buscar articulos por categoria.

# Obtener todos los posts
curl https://jsonplaceholder.typicode.com/posts

# Obtener un post especifico (el post con ID 1)
curl https://jsonplaceholder.typicode.com/posts/1

# Obtener los comentarios de un post
curl https://jsonplaceholder.typicode.com/posts/1/comments

POST - Crear datos

El metodo POST se usa para enviar datos al servidor y crear un nuevo recurso. El cuerpo de la solicitud contiene los datos del recurso que quieres crear.

# Crear un nuevo post
curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mi primer post",
    "body": "Este es el contenido del post",
    "userId": 1
  }'

PUT - Actualizar datos

El metodo PUT se usa para actualizar un recurso existente. Generalmente reemplaza el recurso completo con los nuevos datos proporcionados.

# Actualizar el post con ID 1
curl -X PUT https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "title": "Titulo actualizado",
    "body": "Contenido actualizado del post",
    "userId": 1
  }'

DELETE - Eliminar datos

El metodo DELETE se usa para eliminar un recurso del servidor.

# Eliminar el post con ID 1
curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

Codigos de estado HTTP

Cada respuesta de una API viene acompanada de un codigo de estado HTTP que indica si la solicitud fue exitosa o si hubo algun problema. Los codigos se agrupan en cinco categorias principales:

2xx (Exito): La solicitud fue procesada correctamente. 200 OK significa que todo salio bien, 201 Created indica que un nuevo recurso fue creado exitosamente, y 204 No Content indica exito pero sin contenido en la respuesta (comun al eliminar un recurso).
3xx (Redireccion): El recurso fue movido a otra ubicacion. 301 Moved Permanently indica que la URL cambio de forma permanente, y 304 Not Modified indica que puedes usar la version en cache.
4xx (Error del cliente): Hubo un problema con la solicitud. 400 Bad Request significa que los datos enviados son invalidos, 401 Unauthorized indica que necesitas autenticarte, 403 Forbidden indica que no tienes permisos, y 404 Not Found indica que el recurso no existe.
5xx (Error del servidor): Hubo un problema interno en el servidor. 500 Internal Server Error es un error generico del servidor, y 503 Service Unavailable indica que el servicio esta temporalmente no disponible.

JSON: el formato de datos de las APIs

JSON (JavaScript Object Notation) es el formato mas comun para enviar y recibir datos en APIs REST. Es un formato de texto ligero, facil de leer para humanos y facil de procesar para las maquinas. Un objeto JSON se compone de pares clave-valor encerrados entre llaves:

{
  "id": 1,
  "nombre": "Juan Perez",
  "email": "juan@ejemplo.com",
  "edad": 30,
  "activo": true,
  "direcciones": [
    {
      "tipo": "casa",
      "ciudad": "Lima"
    },
    {
      "tipo": "trabajo",
      "ciudad": "Miraflores"
    }
  ]
}

JSON soporta varios tipos de datos: cadenas de texto (entre comillas), numeros, booleanos (true/false), arrays (listas entre corchetes), objetos anidados y valores nulos (null).

Headers HTTP

Los headers (cabeceras) HTTP son metadatos que acompanan tanto a las solicitudes como a las respuestas. Proporcionan informacion adicional sobre la comunicacion entre el cliente y el servidor. Los headers mas comunes que encontraras al trabajar con APIs REST son:

Content-Type: Indica el formato de los datos que estas enviando. Para JSON, el valor es application/json.
Accept: Indica el formato de datos que esperas recibir del servidor.
Authorization: Contiene las credenciales de autenticacion (token, API key, etc.).
User-Agent: Identifica al cliente que realiza la solicitud.

Autenticacion en APIs

La mayoria de las APIs requieren algun tipo de autenticacion para verificar quien esta realizando las solicitudes y controlar el acceso a los recursos. Los metodos de autenticacion mas comunes son:

API Keys

Una API Key es una clave unica que se asigna a tu aplicacion cuando te registras en el servicio. Se envia en cada solicitud para identificar quien la realiza. Generalmente se incluye como un parametro en la URL o como un header.

# API Key como parametro en la URL
curl "https://api.ejemplo.com/datos?api_key=tu_clave_aqui"

# API Key como header
curl -H "X-API-Key: tu_clave_aqui" https://api.ejemplo.com/datos

Bearer Tokens

Los Bearer Tokens son tokens de acceso que se obtienen despues de un proceso de autenticacion (por ejemplo, iniciando sesion con usuario y contrasena). Son mas seguros que las API Keys porque pueden expirar y ser renovados.

# Usando un Bearer Token en el header Authorization
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.ejemplo.com/datos-protegidos

Ejemplo practico: consumiendo una API con Python

Vamos a poner en practica todo lo que hemos aprendido consumiendo la API publica de JSONPlaceholder, un servicio gratuito que simula una API REST con datos de prueba. Usaremos la libreria requests de Python, que simplifica enormemente el trabajo con APIs.

Instalacion de requests

pip install requests

GET: Obtener datos

import requests

# Obtener todos los posts
respuesta = requests.get("https://jsonplaceholder.typicode.com/posts")

# Verificar que la solicitud fue exitosa
print(f"Codigo de estado: {respuesta.status_code}")

# Convertir la respuesta JSON a un diccionario de Python
posts = respuesta.json()

# Mostrar los primeros 3 posts
for post in posts[:3]:
    print(f"\nID: {post['id']}")
    print(f"Titulo: {post['title']}")
    print(f"Cuerpo: {post['body'][:80]}...")

GET: Obtener un recurso especifico

import requests

# Obtener el post con ID 5
respuesta = requests.get("https://jsonplaceholder.typicode.com/posts/5")

if respuesta.status_code == 200:
    post = respuesta.json()
    print(f"Titulo: {post['title']}")
    print(f"Autor (userId): {post['userId']}")
    print(f"Contenido: {post['body']}")
elif respuesta.status_code == 404:
    print("El post no fue encontrado")
else:
    print(f"Error: {respuesta.status_code}")

POST: Crear un nuevo recurso

import requests

# Datos del nuevo post
nuevo_post = {
    "title": "Mi post creado desde Python",
    "body": "Este post fue creado usando la libreria requests de Python",
    "userId": 1
}

# Enviar la solicitud POST
respuesta = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=nuevo_post  # requests convierte automaticamente el dict a JSON
)

if respuesta.status_code == 201:
    post_creado = respuesta.json()
    print(f"Post creado exitosamente!")
    print(f"ID asignado: {post_creado['id']}")
    print(f"Titulo: {post_creado['title']}")
else:
    print(f"Error al crear el post: {respuesta.status_code}")

PUT: Actualizar un recurso

import requests

# Datos actualizados
datos_actualizados = {
    "id": 1,
    "title": "Titulo completamente nuevo",
    "body": "El contenido ha sido actualizado",
    "userId": 1
}

respuesta = requests.put(
    "https://jsonplaceholder.typicode.com/posts/1",
    json=datos_actualizados
)

if respuesta.status_code == 200:
    post = respuesta.json()
    print(f"Post actualizado: {post['title']}")
else:
    print(f"Error: {respuesta.status_code}")

DELETE: Eliminar un recurso

import requests

respuesta = requests.delete("https://jsonplaceholder.typicode.com/posts/1")

if respuesta.status_code == 200:
    print("Post eliminado exitosamente")
else:
    print(f"Error al eliminar: {respuesta.status_code}")

Filtrado con query parameters

Los query parameters (parametros de consulta) permiten filtrar, ordenar o paginar los resultados de una API. Se anaden al final de la URL despues de un signo de interrogacion ? y se separan con &.

import requests

# Filtrar posts por usuario (userId = 1)
respuesta = requests.get(
    "https://jsonplaceholder.typicode.com/posts",
    params={"userId": 1}
)

posts_usuario = respuesta.json()
print(f"Posts del usuario 1: {len(posts_usuario)}")

for post in posts_usuario:
    print(f"  - {post['title']}")

Manejo de errores robusto

Cuando trabajas con APIs, muchas cosas pueden salir mal: el servidor puede estar caido, tu conexion a internet puede fallar, los datos pueden tener un formato inesperado o tu token de autenticacion puede haber expirado. Un buen manejo de errores es fundamental para crear aplicaciones robustas.

import requests

def obtener_post(post_id):
    """Obtiene un post con manejo de errores robusto."""
    url = f"https://jsonplaceholder.typicode.com/posts/{post_id}"

    try:
        respuesta = requests.get(url, timeout=10)

        # Lanzar excepcion si el codigo de estado indica error
        respuesta.raise_for_status()

        return respuesta.json()

    except requests.exceptions.Timeout:
        print("Error: La solicitud tardo demasiado tiempo")
        return None
    except requests.exceptions.ConnectionError:
        print("Error: No se pudo conectar al servidor")
        return None
    except requests.exceptions.HTTPError as e:
        print(f"Error HTTP: {e.response.status_code}")
        return None
    except requests.exceptions.JSONDecodeError:
        print("Error: La respuesta no es JSON valido")
        return None

# Uso
post = obtener_post(1)
if post:
    print(f"Titulo: {post['title']}")

Buenas practicas al consumir APIs

Para trabajar de forma profesional con APIs REST, ten en cuenta estas recomendaciones:

Lee la documentacion: Antes de escribir una sola linea de codigo, lee la documentacion de la API. Alli encontraras los endpoints disponibles, los parametros requeridos, los formatos de respuesta y los limites de uso.
Respeta los rate limits: La mayoria de las APIs limitan el numero de solicitudes que puedes hacer en un periodo de tiempo. Si excedes el limite, recibiras un error 429 Too Many Requests. Implementa logica de reintento con espera exponencial.
Nunca expongas tus API Keys: No incluyas claves de API directamente en el codigo fuente ni las subas a repositorios publicos. Usa variables de entorno para almacenar credenciales sensibles.
Usa timeouts: Siempre configura un timeout en tus solicitudes para evitar que tu aplicacion se quede esperando indefinidamente si el servidor no responde.
Implementa cache: Si los datos no cambian con frecuencia, almacena las respuestas en cache para reducir el numero de solicitudes y mejorar el rendimiento de tu aplicacion.
Maneja errores graciosamente: Nunca asumas que una solicitud va a ser exitosa. Siempre verifica el codigo de estado y maneja los posibles errores.

Conclusion

Las APIs REST son una de las tecnologias fundamentales del desarrollo de software moderno. Entender como funcionan te abre las puertas a integrar cualquier servicio externo en tus aplicaciones, desde plataformas de pago y redes sociales hasta servicios de inteligencia artificial y datos en tiempo real.

En esta guia hemos cubierto los conceptos fundamentales: que es una API, que es REST, los metodos HTTP, los codigos de estado, el formato JSON, los headers, la autenticacion y como consumir APIs usando curl y Python. Con estos conocimientos, tienes la base necesaria para empezar a trabajar con cualquier API REST.

El siguiente paso es practicar. Elige una API publica que te interese (hay miles disponibles de forma gratuita), lee su documentacion y empieza a experimentar. Cada API que consumas te dara mas experiencia y confianza. Antes de que te des cuenta, estaras integrando servicios complejos y construyendo aplicaciones que se conectan con el mundo.