¿Qué es REST?

REST (Representational State Transfer) es un estilo arquitectónico para construir sistemas distribuidos, propuesto por Roy Fielding en 2000 en su tesis doctoral. REST no es un protocolo o estándar, sino más bien un conjunto de principios y restricciones que el sistema debe seguir.

API (Application Programming Interface) es una interfaz para la interacción entre programas. La API REST, respectivamente, es una API construida de acuerdo con los principios REST.

En pocas palabras, una API REST es una forma de organizar la comunicación entre un cliente y un servidor a través del protocolo HTTP, donde cada recurso (datos) tiene una dirección única (URL) y se puede acceder a él utilizando métodos HTTP estándar.

🔥 100.000+ estudiantes ya están con nosotros

¿Cansado de leer teoría?
¡Hora de programar!

Kodik — una app donde aprendes a programar con práctica. Mentor IA, lecciones interactivas, proyectos reales.

Кодик

Principios básicos de REST

REST se basa en seis principios clave que definen la arquitectura del sistema.

1. Cliente-Servidor

La arquitectura se divide en un cliente que envía solicitudes y un servidor que procesa estas solicitudes y devuelve respuestas. Esta división permite que el cliente y el servidor se desarrollen de forma independiente.

2. Stateless (sin guardar el estado)

Cada solicitud del cliente al servidor debe contener toda la información necesaria para comprender y procesar la solicitud. El servidor no almacena información sobre el estado del cliente entre solicitudes. Si se requiere autenticación, el token se transmite con cada solicitud.

3. Cacheable (Almacenamiento en caché)

Las respuestas del servidor deben indicar claramente si se pueden almacenar en caché. Esto mejora el rendimiento del sistema al reducir el número de solicitudes al servidor.

4. Interfaz uniforme

Este es un principio clave de REST que simplifica la arquitectura del sistema. Incluye cuatro aspectos: identificación de recursos a través de URI, manipulación de recursos a través de vistas, mensajes autodescriptivos y HATEOAS (hipermedios como motor de estado de la aplicación).

5. Sistema en capas

El cliente no puede determinar si está conectado directamente al servidor final o a un nodo intermedio. Esto permite añadir equilibradores de carga, cachés y otros componentes intermedios sin modificar el código del cliente.

6. Código bajo demanda

Este es el único principio opcional. Los servidores pueden ampliar temporalmente la funcionalidad del cliente mediante la transmisión de código ejecutable, como JavaScript.

Métodos HTTP en la API REST

La API REST utiliza métodos HTTP estándar para realizar operaciones con recursos. Cada método tiene un propósito específico:

GET — Obtener datos

El método GET se utiliza para leer datos del servidor. No debe cambiar el estado del recurso.

// Obtener una lista de todos los usuarios
fetch('https://api.example.com/users')
  .then(response => response.json())
  .then(data => console.log(data));

// Obtener un usuario específico
fetch('https://api.example.com/users/123')
  .then(response => response.json())
  .then(data => console.log(data));

POST — Crear un nuevo recurso

POST se utiliza para crear nuevos recursos en el servidor.

fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Ivan Petrov',
    email: 'ivan@example.com'
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

PUT — Actualización completa del recurso

PUT reemplaza el recurso existente con datos completamente nuevos.

fetch('https://api.example.com/users/123', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Ivan Petrov',
    email: 'newemail@example.com',
    age: 30
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

PATCH — Actualización parcial del recurso

PATCH actualiza solo los campos especificados del recurso.

fetch('https://api.example.com/users/123', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newemail@example.com'
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

DELETE — Eliminar recurso

DELETE se utiliza para eliminar un recurso del servidor.

fetch('https://api.example.com/users/123', {
  method: 'DELETE'
})
  .then(response => {
    if (response.ok) {
      console.log('User removed');
    }
  });

Estructura de la API REST

La estructura correcta de la URL en la API de REST es de importancia crítica para comprender y usar la API.

Recursos y colecciones

En REST, todo es un recurso. Los recursos se agrupan en colecciones:

GET    /users           - Получить список пользователей (коллекция)
GET    /users/123       - Получить конкретного пользователя (ресурс)
POST   /users           - Создать нового пользователя
PUT    /users/123       - Обновить пользователя
DELETE /users/123       - Удалить пользователя

Recursos invertidos

Para los recursos relacionados, se utilizan URL anidadas:

GET    /users/123/posts           - Все посты пользователя
GET    /users/123/posts/456       - Конкретный пост пользователя
POST   /users/123/posts           - Создать пост для пользователя
DELETE /users/123/posts/456       - Удалить пост пользователя

Filtrar y ordenar

Utiliza los parámetros de consulta para filtrar, ordenar y paginar:

GET /users?role=admin                    - Фильтрация по роли
GET /users?sort=name&order=asc          - Сортировка по имени
GET /users?page=2&limit=20              - Пагинация
GET /users?search=иван                   - Поиск

Estados de respuesta HTTP

La API REST utiliza códigos de estado HTTP estándar para informar al cliente sobre el resultado de la solicitud.

Respuestas correctas (2xx)

200 OK — solicitud completada con éxito (para GET, PUT, PATCH)
201 Created — recurso creado correctamente (para POST)
204 No Content — la solicitud se completó correctamente, pero no hay contenido para devolver (a menudo para DELETE)

Errores del cliente (4xx)

400 Bad Request — solicitud incorrecta (por ejemplo, JSON no válido)
401 Unauthorized — se requiere autenticación
403 Forbidden — acceso denegado (hay autenticación, pero no hay derechos)
404 Not Found — recurso no encontrado
409 Conflict — conflicto (por ejemplo, ya existe un usuario con este correo electrónico)
422 Unprocessable Entity — validación no aprobada

Errores del servidor (5xx)

500 Internal Server Error — error interno del servidor
503 Service Unavailable — el servicio no está disponible temporalmente

Formato de datos

La API REST generalmente funciona con JSON (JavaScript Object Notation), aunque también se puede usar XML.

Ejemplo de respuesta JSON

{
  "id": 123,
  "name": "Ivan Petrov",
  "email": "ivan@example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "posts": [
    {
      "id": 1,
      "title": "First post",
      "published": true
    }
  ]
}

Ejemplo de error JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Data validation error",
    "details": [
      {
        "field": "email",
        "message": "Incorrect email format"
      }
    ]
  }
}

Autenticación y seguridad

La API REST a menudo requiere autenticación para acceder a recursos protegidos.

JWT (JSON Web Token)

El método de autenticación más popular para la API REST:

// Obtener un token al iniciar sesión
fetch('https://api.example.com/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})
  .then(response => response.json())
  .then(data => {
    // Guardando el token
    localStorage.setItem('token', data.token);
  });

// Uso de un token para solicitudes seguras
fetch('https://api.example.com/users/me', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('token')}`
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

API Keys

Un método simple para las API orientadas a servicios:

fetch('https://api.example.com/data', {
  headers: {
    'X-API-Key': 'your-secret-key'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Control de versiones de la API

A medida que la API evoluciona, es importante mantener la compatibilidad con versiones anteriores. Hay varios enfoques para el control de versiones:

URL Path Versioning

https://api.example.com/v1/users
https://api.example.com/v2/users

Header Versioning

fetch('https://api.example.com/users', {
  headers: {
    'Accept': 'application/vnd.example.v2+json'
  }
})

Query Parameter Versioning

https://api.example.com/users?version=2

Ejemplo práctico: creación de una API REST sencilla en Node.js

Vamos a crear una API REST sencilla para gestionar la lista de tareas.

const express = require('express');
const app = express();

app.use(express.json());

// Almacén temporal de datos
let tasks = [
  { id: 1, title: 'Explore the REST API', completed: false },
  { id: 2, title: 'Create a project', completed: false }
];

let nextId = 3;

// GET - Obtener todas las tareas
app.get('/api/tasks', (req, res) => {
  res.json(tasks);
});

// GET - Obtener una tarea específica
app.get('/api/tasks/:id', (req, res) => {
  const task = tasks.find(t => t.id === parseInt(req.params.id));
  
  if (!task) {
    return res.status(404).json({ 
      error: 'Task not found' 
    });
  }
  
  res.json(task);
});

// POST - Crear una nueva tarea
app.post('/api/tasks', (req, res) => {
  const { title } = req.body;
  
  if (!title) {
    return res.status(400).json({ 
      error: 'Task name is required' 
    });
  }
  
  const newTask = {
    id: nextId++,
    title,
    completed: false
  };
  
  tasks.push(newTask);
  res.status(201).json(newTask);
});

// PUT - Actualizar tarea
app.put('/api/tasks/:id', (req, res) => {
  const taskIndex = tasks.findIndex(t => t.id === parseInt(req.params.id));
  
  if (taskIndex === -1) {
    return res.status(404).json({ 
      error: 'Task not found' 
    });
  }
  
  const { title, completed } = req.body;
  
  tasks[taskIndex] = {
    id: parseInt(req.params.id),
    title: title || tasks[taskIndex].title,
    completed: completed !== undefined ? completed : tasks[taskIndex].completed
  };
  
  res.json(tasks[taskIndex]);
});

// DELETE - Eliminar tarea
app.delete('/api/tasks/:id', (req, res) => {
  const taskIndex = tasks.findIndex(t => t.id === parseInt(req.params.id));
  
  if (taskIndex === -1) {
    return res.status(404).json({ 
      error: 'Task not found' 
    });
  }
  
  tasks.splice(taskIndex, 1);
  res.status(204).send();
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Mejores prácticas en el desarrollo de API REST

1. Usa sustantivos en lugar de verbos

Bien:

GET /users
POST /users

Mal:

GET /getUsers
POST /createUser

2. Utiliza el plural para las colecciones

GET /users (а не /user)
GET /posts (а не /post)

3. Devuelve los códigos HTTP correctos

No devuelvas 200 OK para todas las respuestas. Utilice los códigos de estado apropiados.

4. Proporciona mensajes de error detallados

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Invalid email address provided",
    "field": "email",
    "value": "invalid-email"
  }
}

5. Usa la paginación para colecciones grandes

app.get('/api/users', (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  const startIndex = (page - 1) * limit;
  const endIndex = page * limit;

  const results = {
    data: users.slice(startIndex, endIndex),
    pagination: {
      page,
      limit,
      total: users.length,
      totalPages: Math.ceil(users.length / limit)
    }
  };

  res.json(results);
});

6. Documenta tu API

Utiliza herramientas como Swagger/OpenAPI para documentar la API.

7. Usa HTTPS

Utiliza siempre HTTPS para la transmisión de datos, especialmente cuando trabajes con información confidencial.

8. Implementa la limitación de velocidad

Limite el número de solicitudes de un cliente para protegerse contra el abuso.

REST vs GraphQL vs gRPC

REST no es la única forma de construir una API. Aquí hay una breve comparación:

REST es adecuado para la mayoría de las aplicaciones web estándar, fácil de entender e implementar, tiene un amplio soporte y un excelente almacenamiento en caché.

GraphQL es útil cuando el cliente necesita flexibilidad en la selección de datos, permite obtener todo en una sola solicitud y evitar la sobrecarga o la falta de datos.

gRPC óptimo para arquitectura de microservicios, sistemas de alto rendimiento y API internas, utiliza un protocolo binario y es más rápido que REST.

Herramientas para trabajar con la API REST

Prueba de API

Postman — una herramienta popular para probar API con una interfaz gráfica
Insomnia — alternativa a Postman con una interfaz minimalista
curl - utilidad de consola para solicitudes HTTP

# Ejemplo de uso de curl
curl -X GET https://api.example.com/users
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ivan","email":"ivan@example.com"}'

Bibliotecas de clientes

JavaScript/TypeScript:

Fetch API (incorporado)
Axios
Got

Python:

requests
httpx

PHP:

Guzzle
cURL

Conclusión

La API REST es una tecnología fundamental del desarrollo web moderno que proporciona una forma sencilla y estandarizada de interacción entre el cliente y el servidor. Comprender los principios de REST, usar correctamente los métodos HTTP y los códigos de estado, y seguir las mejores prácticas te ayudará a crear API de alta calidad, escalables y fáciles de mantener.

Comienza con proyectos simples, añadiendo complejidad gradualmente, y no te olvides de la documentación y las pruebas. La API REST es una habilidad que seguirá siendo relevante durante muchos años y te abrirá las puertas al mundo del desarrollo moderno.

Únete a la plataforma educativa Kodik, donde encontrarás cursos estructurados en JavaScript, Node.js, Python y otras tecnologías modernas.

Nuestra amable comunidad de desarrolladores en Telegram ¡Siempre dispuesto a ayudar con preguntas, compartir experiencias y apoyarte en tu camino para convertirte en un programador profesional!

API REST: Guía completa para desarrolladores