Skip to main content

Design an API for an eCommerce order system

An API for an eCommerce order system can be designed following REST principles, using standard HTTP methods like POST, GET, PUT, and DELETE to manage resources. The API should be organized around core entities like orders, products, customers, and payments to facilitate various e-commerce operations.
Below are the key endpoints you would create, categorized by resource:

Orders Endpoints
The orders endpoints manage the lifecycle of an order, from creation to status updates.

Method Endpoint Description
POST /api/orders Create a new order. The request body would contain items, customer details, and shipping information. This would be initiated when a user checks out.
GET /api/orders/{orderId} Retrieve a specific order's details. Provides order status, items purchased, total price, and shipping details.
GET /api/orders?customerId={customerId} List all orders for a specific customer. Useful for displaying a user's order history.
PUT /api/orders/{orderId}/status Update the status of an order. Used internally (e.g., by the fulfillment system) to change status to "Processing", "Shipped", or "Delivered".
DELETE /api/orders/{orderId} Cancel an order. Only allowed if the order is in a specific initial status (e.g., "Pending" or "Created").

Products Endpoints
These endpoints focus on browsing and managing product information.

Method Endpoint Description
GET /api/products List all available products (with pagination and filtering options).
GET /api/products/{productId} Retrieve details of a single product, including price, description, and inventory levels.
GET /api/products?category={category} Filter products by category.
PUT /api/products/{productId}/stock Update product inventory levels. Used by inventory management systems.

Customers & Authentication Endpoints
These endpoints handle customer accounts and authentication processes.

Method Endpoint Description
POST /api/customers/register Create a new customer account.
POST /api/customers/login Authenticate a customer and provide an access token (e.g., JWT).
GET /api/customers/{customerId} Retrieve customer profile information.
PUT /api/customers/{customerId} Update customer details, such as address or contact information.

Payments Endpoints
Payments are often handled by external services, but the API needs endpoints to initiate transactions and confirm results.

Method Endpoint Description
POST /api/orders/{orderId}/payments Initiate a payment for a specific order. The request would likely include a payment token from a provider like Stripe or PayPal.
GET /api/orders/{orderId}/payments/{paymentId} Retrieve the status of a specific payment.
POST /api/webhooks/payment-status Webhook endpoint for payment providers to notify the system of successful or failed payments asynchronously.

Cart Endpoints
For managing items before checkout, dedicated cart endpoints are useful.

Method Endpoint Description
GET /api/carts/{cartId} Retrieve the contents of a shopping cart.
POST /api/carts/{cartId}/items Add a product to the cart.
DELETE /api/carts/{cartId}/items/{itemId} Remove an item from the cart.

Design Principles
  • RESTful Design: The API uses predictable, resource-oriented URLs.
  • HTTP Verbs: Standard HTTP methods map to CRUD operations (Create, Read, Update, Delete).
  • Status Codes: Utilize standard HTTP status codes (e.g., 200 OK for success, 201 Created for new resources, 404 Not Found for missing resources, 400 Bad Request for invalid input, 401 Unauthorized for authentication errors).
  • Authentication & Authorization: Use OAuth 2.0 or similar token-based authentication to secure endpoints, ensuring only authorized users can access or modify their orders.
  • Data Formats: Exchange data primarily in JSON format, which is lightweight and widely supported.
  • Versioning: Include a version number in the URL (e.g., /api/v1/...) to allow for future changes without breaking existing integrations.
Back to top