You need to design an API for obtaining a client's order list with filtering, sorting, and pagination. What endpoints, parameters, response codes, and contract structure would you suggest?

For an API to retrieve a client's order list with filtering, sorting, and pagination, I would suggest the following design:

Endpoint

GET /api/customers/{customerId}/orders

Request parameters

• status — filter by order status (e.g., pending, completed)
• dateFrom, dateTo — filter by date range
• sortBy — field to sort by (e.g., date, amount)
• sortOrder — sort direction (asc or desc)
• page — page number (starting from 1)
• pageSize — number of items per page

Example request

GET /api/customers/123/orders?status=completed&dateFrom=2023-01-01&sortBy=date&sortOrder=desc&page=2&pageSize=20

Response codes

• 200 OK — successful response with data
• 400 Bad Request — invalid request parameters
• 404 Not Found — customer with such ID not found
• 500 Internal Server Error — server error

Response structure (JSON)

{
  "page": 2,
  "pageSize": 20,
  "totalPages": 5,
  "totalItems": 95,
  "orders": [
    {
      "orderId": "abc123",
      "date": "2023-02-15T10:30:00Z",
      "status": "completed",
      "amount": 1500.50,
      "items": [
        {"productId": "p1", "quantity": 2, "price": 500.00},
        {"productId": "p2", "quantity": 1, "price": 500.50}
      ]
    },
    ...
  ]
}

This design provides flexible filtering and sorting, convenient page navigation, and a clear contract for the API client.