Saltar al contenido principal

Diseño de URIs y Nomenclatura de Recursos

🎯 Objetivo​

Regla​

2.1: Se deben diseñar Identificadores Uniformes de Recursos (URIs) que sean intuitivos, consistentes, fáciles de entender y que representen claramente los recursos expuestos por la API. 2.2: Un buen diseño de URI es fundamental y obligatorio para la usabilidad y adopción de la API.

📖 Concepto y Definición​

Regla​

2.3: Cada recurso expuesto por la API debe tener al menos una URI única que actúe como su identificador. 2.4: Las URIs deben ser diseñadas para ser direcciones claras y predecibles para acceder o manipular recursos. 2.5: La nomenclatura (convenciones de nombrado) debe ser consistente en todas las URIs de la API. 2.6: El diseño debe centrarse principalmente en el componente path de la URI (scheme://host:port/path?query#fragment). 2.7: Un recurso debe ser definido como cualquier concepto o entidad nombrable y direccionable (objeto individual, colección, concepto abstracto).

🤔 ¿Por qué es Importante? / Beneficios Clave (Contexto)​

  • Intuitividad y Usabilidad: URIs claras, como se norma, hacen la API más fácil de usar.
  • Predecibilidad: Una nomenclatura consistente, como se norma, permite anticipar cómo acceder a recursos.
  • Mantenibilidad: Un esquema organizado, como se norma, simplifica el mantenimiento.
  • Desacoplamiento: URIs bien definidas, como se norma, ayudan a desacoplar cliente y servidor.
  • Legibilidad: URIs semánticas mejoran la legibilidad de logs.

✅ Buenas Prácticas y Recomendaciones Clave​

Regla​

Do's (Obligatorio):

  • 2.8: Se deben usar sustantivos en plural para denotar colecciones de recursos.
    • Ej: /users, /orders, /products
  • 2.9: Se debe usar el identificador único del recurso en el path para acceder a un elemento específico de una colección.
    • Ej: /users/{userId}, /orders/{orderId}
  • 2.10: Se deben reflejar las jerarquías y relaciones entre recursos en la estructura de la URI para recursos anidados.
    • Ej: /users/{userId}/orders, /users/{userId}/orders/{orderId}
  • 2.11: Se deben usar exclusivamente letras minúsculas en los paths de las URIs para evitar problemas de sensibilidad al caso y mantener consistencia.
    • Ej: /products (Correcto), /Products (Incorrecto)
  • 2.12: Se debe mantener una consistencia estricta en las reglas de nomenclatura y estructura en toda la API.
  • 2.13: Una vez que una URI es pública, no debe cambiarse para evitar romper clientes existentes. El versionado (ver Sección 8) es el mecanismo para gestionar cambios incompatibles en URIs.

Don'ts (Prohibido):

  • 2.14: No se deben usar verbos en las URIs. Las URIs identifican recursos; las acciones son definidas por los métodos HTTP.
    • Prohibido: /getAllUsers, /createUser, /deleteOrder/{orderId}
    • Correcto: GET /users, POST /users, DELETE /orders/{orderId}
  • 2.15: No se deben usar nombres de archivo con extensiones en las URIs. El tipo de contenido debe ser negociado mediante encabezados (Accept, Content-Type).
    • Prohibido: /users.json, /reports/report.xml
  • 2.16: No se deben incluir nombres específicos de tecnología o protocolo en las URIs.
    • Prohibido: /rest/users, /api/json/products
  • 2.17: No se deben usar mayúsculas ni caracteres especiales (excepto guiones - para separar palabras si es necesario, aunque camelCase o simplemente palabras juntas en minúsculas es preferible si la legibilidad se mantiene).
  • 2.18: No se deben usar acrónimos o abreviaturas crípticas. Se debe priorizar la claridad.
  • 2.19: No se deben incluir parámetros que indiquen operaciones CRUD en la URI.
    • Prohibido: /users?action=create

💡 Ejemplos Prácticos (Ilustrativos)​

Ejemplo 1: Recursos Simples y Colecciones (Norma 2.8, 2.9)​

  • Obtener todos los usuarios: GET /users
  • Obtener un usuario específico: GET /users/123
  • Obtener todos los productos: GET /products
  • Obtener un producto específico: GET /products/abc-987

Ejemplo 2: Recursos Anidados y Relaciones (Norma 2.10)​

  • Obtener todos los pedidos del usuario 123: GET /users/123/orders
  • Obtener el pedido 456 del usuario 123: GET /users/123/orders/456
  • Obtener todos los ítems del carrito cart-001: GET /shopping-carts/cart-001/items
  • Obtener el ítem item-789 del carrito cart-001: GET /shopping-carts/cart-001/items/item-789

Ejemplo 3: Evitando Verbos en URIs (Norma 2.14)​

  • Incorrecto:
    • POST /createNewUser
    • GET /getOrdersForUser?userId=123
  • Correcto (según Norma):
    • POST /users (Acción "crear" implícita en POST)
    • GET /users/123/orders (Acción "obtener" implícita en GET)

🛠️ Herramientas y Consideraciones Adicionales (Contexto)​

  • RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax: Es el estándar que define la sintaxis de las URIs.
  • Consistencia es Clave: Aunque existen debates (ej. singular vs. plural), la norma establecida (plural para colecciones) debe seguirse consistentemente dentro de la organización.
  • Complejidad: Se debe evitar que las URIs se vuelvan excesivamente largas o complejas. Si una URI es muy profunda, puede indicar que el recurso es demasiado granular o la relación es muy compleja y debería modelarse de otra forma (ej. parámetros de consulta, cuerpo de solicitud).