Skip to main content
The Products API provides endpoints for creating, reading, updating, and deleting products, as well as processing product sales transactions.

​
Base URL

All product endpoints are prefixed with /orders/products

​
Get Product by ID

Retrieve detailed information about a specific product. 
curl -X GET http://localhost:8080/orders/products/1 \
  -H "Content-Type: application/json"

​
Path Parameters

​
id
Long
required
The unique identifier of the product

​
Response

​
productID
Long
required
Unique identifier of the product
​
productName
String
required
Name of the product
​
productPrice
BigDecimal
required
Price of the product in decimal format
​
productStock
Integer
required
Current stock quantity available

​
Response Example

{
  "productID": 1,
  "productName": "Laptop",
  "productPrice": 999.99,
  "productStock": 50
}

​
Create Product

Create a new product in the system. 
curl -X POST http://localhost:8080/orders/products \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "Laptop",
    "productPrice": 999.99,
    "productStock": 50
  }'

​
Request Body

​
productName
String
required
Name of the product. Must not be null.Validation: @NotNull
​
productPrice
BigDecimal
required
Price of the product. Must be a positive number.Validation: @Positive
​
productStock
Integer
required
Initial stock quantity. Must be zero or positive.Validation: @PositiveOrZero

​
Request Example

{
  "productName": "Laptop",
  "productPrice": 999.99,
  "productStock": 50
}

​
Response

Returns a ProductResponse object with the created product details including the generated productID.
​
productID
Long
required
Auto-generated unique identifier
​
productName
String
required
Name of the product
​
productPrice
BigDecimal
required
Price of the product
​
productStock
Integer
required
Current stock quantity

​
Response Example

{
  "productID": 1,
  "productName": "Laptop",
  "productPrice": 999.99,
  "productStock": 50
}
When a product is successfully created, a ProductCreatedInternalEvent is published to the RabbitMQ exchange for downstream processing.

​
Update Product

Update an existing product’s information. 
curl -X PUT http://localhost:8080/orders/products/1 \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "Gaming Laptop",
    "productPrice": 1299.99,
    "productStock": 30
  }'

​
Path Parameters

​
id
Long
required
The unique identifier of the product to update

​
Request Body

​
productName
String
required
Updated product nameValidation: @NotNull
​
productPrice
BigDecimal
required
Updated product price. Must be positive.Validation: @Positive
​
productStock
Integer
required
Updated stock quantity. Must be zero or positive.Validation: @PositiveOrZero

​
Response

Returns the updated ProductResponse object. 
{
  "productID": 1,
  "productName": "Gaming Laptop",
  "productPrice": 1299.99,
  "productStock": 30
}

​
Delete Product

Delete a product from the system. 
curl -X DELETE http://localhost:8080/orders/products/1 \
  -H "Content-Type: application/json"

​
Path Parameters

​
id
Long
required
The unique identifier of the product to delete

​
Response

Returns HTTP 204 No Content on successful deletion.
This operation permanently deletes the product. This action cannot be undone.

​
Sell Product

Process a product sale transaction. This endpoint handles inventory deduction and publishes sale events for downstream processing. 
curl -X POST http://localhost:8080/orders/products/1/sell \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 5
  }'

​
Path Parameters

​
id
Long
required
The unique identifier of the product to sell

​
Request Body

​
quantity
Integer
required
The number of units to sell

​
Request Example

{
  "quantity": 5
}

​
Response

Returns HTTP 202 Accepted, indicating the sale request has been received and is being processed asynchronously.
The endpoint automatically captures the client IP address from the HTTP request for fraud detection and monitoring purposes.

​
Event Flow

When a sale is processed:
  1. The product stock is decremented by the requested quantity
  2. A ProductSoldInternalEvent is published to RabbitMQ
  3. The Sentinel service consumes this event for fraud detection
  4. If suspicious activity is detected, an AlertInternalEvent is generated
  5. The Notify service receives alerts and sends notifications

​
Data Models

​
ProductRequest

Used for creating and updating products. 
public record ProductRequest(
    @NotNull String productName,
    @Positive BigDecimal productPrice,
    @PositiveOrZero Integer productStock
)

​
ProductResponse

Returned when retrieving or modifying products. 
public record ProductResponse(
    Long productID,
    String productName,
    BigDecimal productPrice,
    Integer productStock
)

​
BuyRequest

Used for product sale transactions. 
public record BuyRequest(Integer quantity)

​
Error Responses

All endpoints may return the following error responses:
Status CodeDescription
400Bad Request - Invalid input data or validation failure
404Not Found - Product does not exist
500Internal Server Error - Unexpected server error

​
Error Response Example

{
  "timestamp": "2026-03-05T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Product not found with id: 1",
  "path": "/orders/products/1"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us