Documentación de la API REST (API Gateway)

Esta página detalla los endpoints REST expuestos por el API Gateway.

URL Base: http://<GATEWAY_HOST>:<GATEWAY_PORT> (Ej: http://localhost:8080)

---

Usuarios

Obtener Usuario por ID

• Endpoint: GET /api/users/{userId}
• Descripción: Recupera los detalles de un usuario específico.
• Parámetros de Ruta:
  • userId (string): El ID del usuario a buscar.
• Respuesta Exitosa (200 OK):

  {
    "status": "success",
    "users": [
      {
        "userId": "1",
        "name": "Alice",
        "email": "[email protected]",
        "balance": 99551.5 // Ejemplo de saldo actualizado
      }
    ]
  }
  

• Respuestas de Error:
  • 404 Not Found: Si el usuario no existe.

  { "status": 404, "error": "Not Found", "message": "Usuario con ID 1 no encontrado." }
  

  • 503 Service Unavailable: Si el User Service no está disponible (y no se pudo encolar/no aplica).

  { "status": 503, "error": "Service Unavailable", "message": "El servicio subyacente no está disponible." }
  

---

Productos

Obtener Producto por ID

• Endpoint: GET /api/products/{productId}
• Descripción: Recupera los detalles de un producto específico.
• Parámetros de Ruta:
  • productId (string): El ID del producto a buscar.
• Respuesta Exitosa (200 OK):

  {
    "id": "1",
    "name": "Laptop Gamer",
    "price": 199.0,
    "description": "Una laptop potente."
  }
  

• Respuestas de Error:
  • 404 Not Found: Si el producto no existe.
  • 503 Service Unavailable: Si el Product Service no está disponible.

---

Órdenes

Crear una Orden

• Endpoint: POST /api/orders
• Descripción: Crea una nueva orden para un usuario con productos específicos. Orquesta llamadas a los servicios de Usuario y Producto, y actualiza el saldo del usuario. Utiliza MOM para failover.
• Cuerpo de la Solicitud (Request Body): application/json

  {
    "userId": "1",
    "productIds": ["1", "2"]
  }
  

• Respuesta Exitosa (201 Created):

  {
    "id": "1745194637551", // ID generado por el servicio
    "userId": "1", // o user_id según el proto/implementación
    "productIds": ["1", "2"], // o product_ids
    "status": "CREATED",
    "total": 448.50 // El total calculado
  }
  

• Respuesta Aceptada (202 Accepted):
  • Indica que la solicitud fue recibida pero un servicio subyacente (User, Product, o el propio Order Service temporalmente) no estaba disponible y la solicitud se encoló en RabbitMQ para procesamiento posterior.

  {
    "status": "accepted",
    "message": "La solicitud ha sido aceptada y será procesada. Puede que el servicio subyacente no esté disponible temporalmente."
  }
  

• Respuestas de Error Directas:
  • 400 Bad Request: Si falta userId o productIds, o si tienen formato incorrecto.

  { "status": 400, "error": "Bad Request", "message": "Se requiere 'userId' (string) y 'productIds' (array no vacío)." }
  

  • 404 Not Found: Si el userId o alguno de los productIds no existen y el error no es considerado retryable por el Gateway.

  { "status": 404, "error": "Not Found", "message": "Usuario 999 no encontrado" }
  // o
  { "status": 404, "error": "Not Found", "message": "Producto 999 inválido" }
  

  • 412 Precondition Failed (o 400 Bad Request según mapeo): Si el usuario no tiene saldo suficiente.

  { "status": 412, "error": "Precondition Failed", "message": "Saldo insuficiente (10.0 < 50.0)" }
  

  • 503 Service Unavailable: Si un servicio requerido falla de forma no retryable o si RabbitMQ falla al encolar.

Obtener Orden por ID

• Endpoint: GET /api/orders/{orderId}
• Descripción: Recupera los detalles de una orden específica por su ID.
• Parámetros de Ruta:
  • orderId (string): El ID de la orden a buscar.
• Respuesta Exitosa (200 OK):

  {
    "id": "1745194637551",
    "userId": "1", // o user_id
    "productIds": ["1", "2", "3"], // o product_ids
    "status": "CREATED",
    "total": 488.40
  }
  

• Respuestas de Error:
  • 404 Not Found: Si la orden no existe.

Obtener Órdenes por ID de Usuario

• Endpoint: GET /api/orders-user/{userId}
• Descripción: Recupera todas las órdenes asociadas a un usuario específico.
• Parámetros de Ruta:
  • userId (string): El ID del usuario cuyas órdenes se buscan.
• Respuesta Exitosa (200 OK):

  {
    "orders": [
      {
        "id": "1744906771993",
        "userId": "1", // o user_id
        "productIds": ["1"], // o product_ids
        "status": "CREATED",
        "total": 199.0
      },
      {
        "id": "1745194637551",
        "userId": "1", // o user_id
        "productIds": ["1", "2", "3"], // o product_ids
        "status": "CREATED",
        "total": 488.40
      }
      // ... más órdenes si existen
    ]
  }
  

  • Si el usuario no tiene órdenes, la respuesta será 200 OK con "orders": [].
• Respuestas de Error:
  • 500 Internal Server Error / 503 Service Unavailable: Si hay problemas al contactar el Order Service.