Skip to content

orders-api-reference.md

Latest commit

 

History

History
505 lines (405 loc) · 10.8 KB

orders-api-reference.md

File metadata and controls

505 lines (405 loc) · 10.8 KB
Raw

Orders API Reference

Complete API documentation for the Orders endpoints of the PC Components Store API.

Base URL

http://localhost:8080

Authentication

All order endpoints require authentication. Include the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Authorization Rules

  • Customers: Can only view and create their own orders
  • Admins: Can view all orders and update order statuses

Get All Orders

GET /api/orders

Retrieve orders. Admin sees all orders; customers see only their own.

Authorization: Bearer token required

Success Response (Admin)

HTTP/1.1 200 OK
[
  {
    "id": 1,
    "userId": 5,
    "userEmail": "customer@example.com",
    "orderDate": "2024-01-10T14:30:00Z",
    "totalAmount": 1299.98,
    "status": "processing",
    "shippedAt": null,
    "deliveredAt": null,
    "orderItems": [
      {
        "id": 1,
        "productId": 1,
        "productName": "Intel Core i7-12700K",
        "quantity": 1,
        "unitPrice": 409.99,
        "subtotal": 409.99
      },
      {
        "id": 2,
        "productId": 5,
        "productName": "NVIDIA GeForce RTX 3080",
        "quantity": 1,
        "unitPrice": 699.99,
        "subtotal": 699.99
      }
    ]
  }
]

Success Response (Customer)

HTTP/1.1 200 OK
[
  {
    "id": 1,
    "userId": 5,
    "userEmail": "customer@example.com",
    "orderDate": "2024-01-10T14:30:00Z",
    "totalAmount": 1299.98,
    "status": "processing",
    "shippedAt": null,
    "deliveredAt": null,
    "orderItems": [
      {
        "id": 1,
        "productId": 1,
        "productName": "Intel Core i7-12700K",
        "quantity": 1,
        "unitPrice": 409.99,
        "subtotal": 409.99
      }
    ]
  }
]

Response Schema (OrderDto)

Field Type Description
id int Order ID
userId int User ID who placed the order
userEmail string? User email
orderDate DateTime Order creation timestamp
totalAmount decimal Total order amount
status string Order status (see Status Values below)
shippedAt DateTime? Shipment timestamp (null if not shipped)
deliveredAt DateTime? Delivery timestamp (null if not delivered)
orderItems OrderItemDto[] List of order items

Response Schema (OrderItemDto)

Field Type Description
id int Order item ID
productId int Product ID
productName string? Product name
quantity int Quantity ordered
unitPrice decimal Price per unit at order time
subtotal decimal Computed: quantity × unitPrice

Example Request

# Admin: View all orders
curl http://localhost:8080/api/orders \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Customer: View own orders
curl http://localhost:8080/api/orders \
  -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN"

Get Order by ID

GET /api/orders/{id}

Retrieve a specific order. Admin can access any order; customers can only access their own.

Authorization: Bearer token required

Path Parameters

Parameter Type Required Description
id int Yes Order ID

Success Response

HTTP/1.1 200 OK
{
  "id": 1,
  "userId": 5,
  "userEmail": "customer@example.com",
  "orderDate": "2024-01-10T14:30:00Z",
  "totalAmount": 1299.98,
  "status": "processing",
  "shippedAt": null,
  "deliveredAt": null,
  "orderItems": [
    {
      "id": 1,
      "productId": 1,
      "productName": "Intel Core i7-12700K",
      "quantity": 1,
      "unitPrice": 409.99,
      "subtotal": 409.99
    }
  ]
}

Error Responses

Status Code Description
404 Not Found Order does not exist
401 Unauthorized Missing or invalid token
403 Forbidden Customer trying to access another user's order

Example Request

curl http://localhost:8080/api/orders/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Order

POST /api/orders

Create a new order. Requires authentication.

Authorization: Bearer token required

Request Body

{
  "items": [
    {
      "productId": 1,
      "quantity": 2
    },
    {
      "productId": 5,
      "quantity": 1
    }
  ]
}

Request Schema (CreateOrderRequest)

Field Type Required Description
items OrderItemRequest[] Yes List of items to order

Request Schema (OrderItemRequest)

Field Type Required Description
productId int Yes Product ID
quantity int Yes Quantity to order (must be > 0)

Success Response

HTTP/1.1 201 Created
{
  "id": 10,
  "userId": 5,
  "userEmail": "customer@example.com",
  "orderDate": "2024-01-15T10:30:00Z",
  "totalAmount": 1219.97,
  "status": "pending",
  "shippedAt": null,
  "deliveredAt": null,
  "orderItems": [
    {
      "id": 20,
      "productId": 1,
      "productName": "Intel Core i7-12700K",
      "quantity": 2,
      "unitPrice": 409.99,
      "subtotal": 819.98
    },
    {
      "id": 21,
      "productId": 5,
      "productName": "NVIDIA GeForce RTX 3080",
      "quantity": 1,
      "unitPrice": 699.99,
      "subtotal": 699.99
    }
  ]
}

Error Responses

Status Code Description
400 Bad Request Product not found, insufficient stock, or invalid quantity
401 Unauthorized Missing or invalid token

Stock Handling

  • Stock is automatically decremented when order is created
  • If any product has insufficient stock, the entire order is rejected

Example Request

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN" \
  -d '{
    "items": [
      {
        "productId": 1,
        "quantity": 2
      },
      {
        "productId": 5,
        "quantity": 1
      }
    ]
  }'

Update Order Status (Admin Only)

PATCH /api/orders/{id}/status

Update the status of an order. Requires admin role.

Authorization: Bearer token with "admin" role

Path Parameters

Parameter Type Required Description
id int Yes Order ID

Request Body

{
  "status": "shipped"
}

Request Schema (UpdateOrderStatusRequest)

Field Type Required Description
status string Yes New order status

Status Values

Status Description
pending Order received, awaiting processing
processing Order is being prepared
shipped Order has been shipped
delivered Order has been delivered
cancelled Order has been cancelled

Automatic Timestamps

  • Setting status to shipped automatically sets shippedAt to current UTC time
  • Setting status to delivered automatically sets deliveredAt to current UTC time

Success Response

HTTP/1.1 200 OK
{
  "message": "Order status updated successfully"
}

Error Responses

Status Code Description
404 Not Found Order does not exist
400 Bad Request Invalid status value
401 Unauthorized Missing or invalid token
403 Forbidden User is not an admin

Example Request

# Update order status to shipped
curl -X PATCH http://localhost:8080/api/orders/1/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "status": "shipped"
  }'

Request/Response Models

CreateOrderRequest

{
  "items": [
    {
      "productId": 1,
      "quantity": 2
    },
    {
      "productId": 5,
      "quantity": 1
    }
  ]
}
Field Type Required Description
items OrderItemRequest[] Yes List of items to order

OrderItemRequest

{
  "productId": 1,
  "quantity": 2
}
Field Type Required Validation
productId int Yes Must exist
quantity int Yes Must be > 0

UpdateOrderStatusRequest

{
  "status": "shipped"
}
Field Type Required Validation
status string Yes One of: pending, processing, shipped, delivered, cancelled

OrderDto

{
  "id": 1,
  "userId": 5,
  "userEmail": "customer@example.com",
  "orderDate": "2024-01-10T14:30:00Z",
  "totalAmount": 1299.98,
  "status": "processing",
  "shippedAt": null,
  "deliveredAt": null,
  "orderItems": [
    {
      "id": 1,
      "productId": 1,
      "productName": "Intel Core i7-12700K",
      "quantity": 1,
      "unitPrice": 409.99,
      "subtotal": 409.99
    }
  ]
}
Field Type Description
id int Order ID
userId int User ID who placed the order
userEmail string? User email
orderDate DateTime Order creation timestamp
totalAmount decimal Total order amount
status string Order status
shippedAt DateTime? Shipment timestamp (null if not shipped)
deliveredAt DateTime? Delivery timestamp (null if not delivered)
orderItems OrderItemDto[] List of order items

OrderItemDto

{
  "id": 1,
  "productId": 1,
  "productName": "Intel Core i7-12700K",
  "quantity": 1,
  "unitPrice": 409.99,
  "subtotal": 409.99
}
Field Type Description
id int Order item ID
productId int Product ID
productName string? Product name
quantity int Quantity ordered
unitPrice decimal Price per unit at order time
subtotal decimal Computed: quantity × unitPrice

Error Responses

Standard Error Format

{
  "error": "Error message description"
}

HTTP Status Codes

Code Description
200 OK Request successful
201 Created Resource created successfully
204 No Content Request successful, no content to return
400 Bad Request Invalid input or validation failed
401 Unauthorized Missing or invalid authentication
403 Forbidden User lacks required permissions
404 Not Found Resource does not exist