S01L02 - URIs basadas en recursos

html

URIs Basadas en Recursos: Una Guía Completa

Tabla de Contenidos

Introducción
Comprendiendo las URIs Basadas en Recursos
URIs Basadas en Acciones vs. URIs Basadas en Recursos
Diseñando URIs Basadas en Recursos Efectivas
Métodos HTTP en URIs Basadas en Recursos
Códigos de Estado HTTP Explicados
Implementando URIs Basadas en Recursos: Un Ejemplo Práctico
Mejores Prácticas y Convenciones
Conclusión


Introducción
En el ámbito del desarrollo web y el diseño de API, los Identificadores Uniformes de Recursos (URIs) juegan un papel fundamental en la definición de cómo se acceden y manipulan los recursos. Este eBook se adentra en las URIs basadas en recursos, un concepto fundamental para crear APIs RESTful que son intuitivas, escalables y mantenibles.
Comprender las URIs basadas en recursos es esencial para los desarrolladores que buscan diseñar APIs que se adhieran a las mejores prácticas, asegurando claridad y eficiencia en la comunicación entre clientes y servidores. Esta guía explorará las diferencias entre URIs basadas en acciones y URIs basadas en recursos, la importancia de los métodos HTTP, los códigos de estado, y proporcionará ejemplos prácticos para solidificar tu comprensión.
Pros y Contras de las URIs Basadas en Recursos
Pros:

Claridad: Mejora la legibilidad y comprensión al estructurar las URIs alrededor de recursos.
Escalabilidad: Facilita la expansión y el mantenimiento de las APIs.
Consistencia: Promueve la uniformidad a través de diferentes endpoints, haciendo la API más predecible.

Contras:

Complejidad Inicial: Puede requerir una comprensión más profunda de los principios REST.
Rigidez: La adhesión estricta puede a veces limitar la flexibilidad en ciertos escenarios.

Resumen Comparativo



Característica
URIs Basadas en Acciones
URIs Basadas en Recursos




Estructura
Usa verbos que indican acciones (e.g., /getBrands)
Se centra en recursos (e.g., /brands)


Legibilidad
Pueden ser confusas debido a términos de acción variados
Más intuitivas y organizadas alrededor de la jerarquía de recursos


Cumplimiento REST
Menos alineadas con los principios RESTful
Totalmente adherentes a los estándares RESTful


Escalabilidad
Pueden volverse engorrosas a medida que la API crece
Fácilmente escalables con una gestión clara de recursos




Capítulo 1: Comprendiendo las URIs Basadas en Recursos
¿Qué son las URIs Basadas en Recursos?
Las URIs Basadas en Recursos son endpoints que representan recursos específicos dentro de una aplicación o servicio. En lugar de enfocarse en acciones u operaciones, estas URIs se estructuran alrededor de las entidades que representan, como brands, bikes y spares en un contexto de showroom.
Importancia de las URIs Basadas en Recursos
Adoptar URIs basadas en recursos alinea el diseño de tu API con los principios RESTful, promoviendo la escalabilidad, mantenibilidad y claridad. Este enfoque simplifica la interacción entre clientes y servidores al proporcionar una forma clara y consistente de acceder y manipular recursos.
Cuándo y Dónde Usar las URIs Basadas en Recursos
Las URIs basadas en recursos son ideales para:

APIs RESTful: Asegurando la adherencia a los estándares REST.
Arquitectura de Microservicios: Facilitando un diseño de servicio modular y escalable.
Cualquier Diseño de API: Donde la claridad y la mantenibilidad son prioridades.


Capítulo 2: URIs Basadas en Acciones vs. URIs Basadas en Recursos
URIs Basadas en Acciones
Las URIs basadas en acciones incorporan verbos para denotar acciones u operaciones específicas. Por ejemplo:

/getBrands
/setBikes
/deleteSpare?id=25

Si bien este enfoque puede funcionar, a menudo conduce a confusión e inconsistencia, especialmente a medida que la API crece.
URIs Basadas en Recursos
Las URIs basadas en recursos se enfocan en las entidades involucradas:

/brands
/brands/bajaj
/bikes/honda

Esta estructura mejora la legibilidad y se alinea con las mejores prácticas RESTful.
Análisis Comparativo



Aspecto
URIs Basadas en Acciones
URIs Basadas en Recursos




Uso de Verbos
Incluye verbos de acción (get, set)
Usa sustantivos que representan recursos


Claridad
Menos intuitivo
Más intuitivo y organizado


Cumplimiento REST
Menos alineado con los principios REST
Totalmente adherente a los estándares RESTful


Mantenimiento
Pueden volverse engorrosas
Más fácil de mantener y escalar




Capítulo 3: Diseñando URIs Basadas en Recursos Efectivas
Estructurando tus URIs
Las URIs basadas en recursos efectivas siguen una estructura jerárquica, representando las relaciones entre recursos. Por ejemplo:

/brands – Accediendo a todas las marcas.
/brands/bajaj – Accediendo a una marca específica, Bajaj.
/bikes/honda – Accediendo a todas las bikes bajo la marca Honda.
/spares/suzuki – Accediendo a spares relacionados con Suzuki.
/spares/25 – Accediendo a una pieza de repuesto específica por ID.

Mejores Prácticas

Usar Sustantivos en Plural: Representar colecciones en forma plural (e.g., /brands).
Representación de Jerarquía: Reflejar la relación entre recursos a través de la estructura de la URI.
Convenciones de Nomenclatura Consistentes: Mantener uniformidad en los nombres de las URIs para predecibilidad.

Ejemplo Práctico
Imagina una API de showroom donde puedes acceder a diferentes marcas, sus bikes y piezas de repuesto. Una estructura de URIs basada en recursos bien diseñada podría verse así:




		
		
			
			
Java
			
			/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
			
				
					
				
					1
2
3
4
5
6
7
				
						/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
					
				
			
		



Capítulo 4: Métodos HTTP en URIs Basadas en Recursos
Visión General de los Métodos HTTP
Los métodos HTTP definen las acciones que se pueden realizar sobre los recursos. Los métodos más comúnmente usados en APIs RESTful son:

GET: Recuperar información.
POST: Crear un nuevo recurso.
PUT: Actualizar un recurso existente.
DELETE: Eliminar un recurso.

Explicación Detallada

GET: Usado para obtener datos de un recurso. Por ejemplo, GET /brands recupera todas las marcas.
POST: Usado para crear un nuevo recurso. Por ejemplo, POST /brands añade una nueva marca.
PUT: Usado para actualizar un recurso existente. Por ejemplo, PUT /brands/bajaj actualiza la información de la marca Bajaj.
DELETE: Usado para eliminar un recurso. Por ejemplo, DELETE /spares/25 elimina la pieza de repuesto con ID 25.

Mapeo de Métodos a Operaciones



Método HTTP
Operación
Ejemplo de URI




GET
Recuperar recurso(s)
/brands


POST
Crear un nuevo recurso
/brands


PUT
Actualizar un recurso existente
/brands/bajaj


DELETE
Eliminar un recurso
/spares/25




Capítulo 5: Códigos de Estado HTTP Explicados
Importancia de los Códigos de Estado
Los códigos de estado HTTP comunican el resultado de la solicitud de un cliente al servidor. Proporcionan retroalimentación esencial sobre si la operación fue exitosa o si ocurrieron errores.
Códigos de Estado Comunes

200 OK: La solicitud fue exitosa.
201 Created: Un nuevo recurso fue creado exitosamente.
404 Not Found: El recurso solicitado no existe.
500 Internal Server Error: Ocurrió un error genérico en el servidor.

Categorización de los Códigos de Estado



Categoría
Rango de Códigos
Descripción




1xx
100-199
Respuestas informativas


2xx
200-299
Respuestas exitosas


3xx
300-399
Mensajes de redirección


4xx
400-499
Respuestas de error del cliente


5xx
500-599
Respuestas de error del servidor



Uso Práctico
Cuando un cliente hace una solicitud a GET /brands, una recuperación exitosa retornaría un estado 200 OK. Intentar acceder a una pieza de repuesto inexistente usando GET /spares/999 resultaría en un estado 404 Not Found.

Capítulo 6: Implementando URIs Basadas en Recursos: Un Ejemplo Práctico
Escenario: API de Showroom
Consideremos un showroom que gestiona brands, bikes y spares. Implementaremos URIs basadas en recursos para manejar estas entidades.
Ejemplos de URIs
Brands:

GET /brands – Recuperar todos las brands.
GET /brands/bajaj – Recuperar información sobre Bajaj.
POST /brands – Añadir una nueva brand.
PUT /brands/bajaj – Actualizar la información de Bajaj.
DELETE /brands/bajaj – Remover a Bajaj del sistema.

Bikes:

GET /bikes – Recuperar todas las bikes.
GET /bikes/honda – Recuperar bikes de Honda.
POST /bikes – Añadir una nueva bike.
PUT /bikes/honda – Actualizar la información de las bikes de Honda.
DELETE /bikes/honda – Remover las bikes de Honda.

Spares:

GET /spares – Recuperar todas las piezas de repuesto.
GET /spares/suzuki – Recuperar spares para Suzuki.
GET /spares/25 – Recuperar la pieza de repuesto con ID 25.
POST /spares – Añadir una nueva pieza de repuesto.
PUT /spares/25 – Actualizar la pieza de repuesto con ID 25.
DELETE /spares/25 – Remover la pieza de repuesto con ID 25.

Ejemplo de Implementación de Código
A continuación se muestra un ejemplo simple usando Node.js y Express para implementar URIs basadas en recursos para gestionar brands.




		
		
			
			
Java
			
			const express = require('express');
const app = express();
app.use(express.json());

let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];

// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});

// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});

// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});

// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});

// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
				
						const express = require('express');
const app = express();
app.use(express.json());
 
let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];
 
// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});
 
// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});
 
// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});
 
// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});
 
// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});
 
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
					
				
			
		


Explicación del Código

Configuración: Inicializamos una aplicación Express y definimos un array de muestra brands.
GET /brands: Recupera la lista de todas las brands, respondiendo con un estado 200 OK.
GET /brands/:name: Obtiene una brand específica por nombre. Si no se encuentra, retorna un 404 Not Found.
POST /brands: Añade una nueva brand a la colección, respondiendo con un estado 201 Created.
PUT /brands/:name: Actualiza el nombre de una brand existente. Si la brand no existe, retorna un 404 Not Found.
DELETE /brands/:name: Remueve una brand de la colección. Si la brand no se encuentra, retorna un 404 Not Found.

Ejemplo de Salida
Solicitud: GET /brands
Respuesta:




		
		
			
			
Java
			
			[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
			
				
					
				
					1
2
3
4
				
						[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
					
				
			
		



Capítulo 7: Mejores Prácticas y Convenciones
Nombre Consistente
Usa sustantivos en plural para los nombres de recursos para representar colecciones. Por ejemplo, usa /brands en lugar de /brand.
Estructuración Jerárquica
Refleja la relación entre recursos a través de la estructura de la URI. Los recursos anidados deberían representar su jerarquía de forma lógica.
Uso de Métodos HTTP
Aprovecha los métodos HTTP apropiados para realizar operaciones sobre los recursos, asegurando la adherencia a los principios RESTful.
Versionado
Implementa versionado en tus URIs para gestionar cambios a lo largo del tiempo sin interrumpir a los clientes existentes. Por ejemplo:




		
		
			
			
Java
			
			/v1/brands
/v2/brands
			
				
					
				
					1
2
				
						/v1/brands
/v2/brands
					
				
			
		


Manejo de Errores
Proporciona mensajes de error significativos y códigos de estado HTTP apropiados para ayudar a los clientes a entender el resultado de sus solicitudes.
Documentación
Mantén una documentación completa de tu API, detallando los endpoints disponibles, métodos, parámetros y respuestas esperadas.

Conclusión
Las URIs basadas en recursos son una piedra angular en el diseño de APIs RESTful, ofreciendo un enfoque estructurado e intuitivo para gestionar recursos. Al enfocarse en las entidades en lugar de las acciones, los desarrolladores pueden crear APIs que son escalables, mantenibles y fácilmente entendidas por los clientes.
Adoptar las mejores prácticas en el diseño de URIs, el uso apropiado de los métodos HTTP y el manejo efectivo de errores asegura que tus APIs no solo cumplan con los requisitos actuales, sino que también sean adaptables a necesidades futuras. Ya sea que estés construyendo una aplicación simple o una arquitectura de microservicios compleja, las URIs basadas en recursos proporcionan la base para un desarrollo de API robusto y eficiente.
Nota: Este artículo fue generado por IA.
Método HTTP	Operación	Ejemplo de URI
GET	Recuperar recurso(s)	/brands
POST	Crear un nuevo recurso	/brands
PUT	Actualizar un recurso existente	/brands/bajaj
DELETE	Eliminar un recurso	/spares/25
Característica	URIs Basadas en Acciones	URIs Basadas en Recursos
Estructura	Usa verbos que indican acciones (e.g., /getBrands)	Se centra en recursos (e.g., /brands)
Legibilidad	Pueden ser confusas debido a términos de acción variados	Más intuitivas y organizadas alrededor de la jerarquía de recursos
Cumplimiento REST	Menos alineadas con los principios RESTful	Totalmente adherentes a los estándares RESTful
Escalabilidad	Pueden volverse engorrosas a medida que la API crece	Fácilmente escalables con una gestión clara de recursos
Aspecto	URIs Basadas en Acciones	URIs Basadas en Recursos
Uso de Verbos	Incluye verbos de acción (get, set)	Usa sustantivos que representan recursos
Claridad	Menos intuitivo	Más intuitivo y organizado
Cumplimiento REST	Menos alineado con los principios REST	Totalmente adherente a los estándares RESTful
Mantenimiento	Pueden volverse engorrosas	Más fácil de mantener y escalar
Categoría	Rango de Códigos	Descripción
1xx	100-199	Respuestas informativas
2xx	200-299	Respuestas exitosas
3xx	300-399	Mensajes de redirección
4xx	400-499	Respuestas de error del cliente
5xx	500-599	Respuestas de error del servidor