Mastering E‑Commerce API Design: Best Practices, Protocols, and Versioning

Introduction: In this deep dive we start from the basics and gradually explore API design, presenting technical best practices for defining excellent APIs.

API Design: E‑Commerce Example

Consider an API for an e‑commerce platform like Shopify, a well‑known service that lets businesses create online stores.

In API design we focus on defining the API's input (e.g., new product details) and output (e.g., information returned when a product is queried).

We concentrate on the interface without worrying about underlying implementation.

API Design and CRUD

API design mainly defines how CRUD operations are exposed and mapped to e‑commerce interactions.

CRUD stands for Create, Read, Update, Delete – the basic operations for any data‑driven application.

To add a new product (Create), send a POST request to /api/products with product details in the request body.

To retrieve products (Read), use a GET request to /products.

To update product information (Update), use PUT or PATCH on /products/:id, where :id is the product identifier.

To delete a product, send a DELETE request to /products/:id.

Communication Protocols and Data Transfer Mechanisms

Another part is choosing the communication protocol (HTTP, WebSockets, etc.) and data format (JSON, XML, Protocol Buffers).

RESTful APIs are common, but GraphQL and gRPC are also options.

REST (Representational State Transfer)

Advantages: Stateless; each request contains all information needed. Uses standard HTTP methods (GET, POST, PUT, DELETE). Works across browsers and mobile apps.

Disadvantages: May lead to over‑fetching or under‑fetching data, requiring many endpoints for specific data.

Features: Supports pagination, filtering (limit, offset), sorting, and uses JSON for data exchange.

GraphQL

Advantages: Clients request exactly the data they need, avoiding over‑ or under‑fetching. Strongly typed, schema‑based queries.

Disadvantages: Complex queries can impact server performance; all requests are sent as POST.

Characteristics: Responses use HTTP 200 status even for errors, with error details in the response body.

gRPC (Google Remote Procedure Call)

Advantages: Built on HTTP/2, offering multiplexing and server push. Uses Protocol Buffers, a language‑neutral, platform‑neutral, efficient serialization format. Highly efficient for bandwidth‑constrained environments, ideal for microservices.

Disadvantages: Less human‑readable than JSON and requires HTTP/2 support.

Characteristics: Supports streaming and bidirectional communication, making it suitable for server‑to‑server interactions.

Relationships in API Design

In an e‑commerce context, entities such as users, orders, and products have relationships. For example, GET /users/{userId}/orders should retrieve orders for a specific user.

GET Requests: Query, Limits, and Idempotency

Common query parameters include limit for pagination offsets and startDate / endDate for date‑range filtering, allowing users to retrieve specific data subsets without overwhelming the system.

A well‑designed GET request is idempotent, meaning repeated calls produce the same result and never modify data.

Backward Compatibility and Versioning

When modifying endpoints, maintaining backward compatibility is crucial to avoid breaking existing clients.

Versioning (e.g., /v2/products) is a common practice for handling major changes.

For GraphQL, adding new fields (v2 fields) without removing old ones improves the API without breaking existing clients.

Rate Limiting and CORS

Setting rate limits controls how many requests a user can make within a time window, preserving API reliability and preventing DDoS attacks.

Configuring CORS (Cross‑Origin Resource Sharing) is essential for web security, specifying which domains may access the API.

Next Steps

API design is only one part of system design interviews. For more concepts and best practices, explore additional system design resources.