For example, to add a new product (Create), you would make a POST request to /api/products where the product details are sent in the request body.

To retrieve products (Read), you need to fetch data with a GET request from /products.

For updating product information (Update), we use PUT or PATCH requests to /products/:id, where id is the id of a product we need to update.

Removing is similar to updating; we make a DELETE request to /products/:id where id is the product we need to remove (Delete).

Communication Protocol and Data Transport Mechanism

Another part is to decide on the Communication Protocol that will be used, like HTTP, WebSockets, etc, and the Data Transport Mechanism: JSON, XML, or Protocol Buffers.

This is the case with RESTful APIs, but we also have GraphQL or gRPC paradigms

API Paradigms

APIs come in different paradigms, each with its own set of protocols and standards.

REST (Representational State Transfer)

Pros: Stateless: Each request from a client to a server must contain all the information needed to understand and complete the request. Uses standard HTTP methods (GET, POST, PUT, DELETE). Easily consumable by different clients (browsers, mobile apps).

Cons: This can lead to over-fetching or under-fetching of data- because More endpoints may be required to access specific data.

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

GraphQL

Pros: Allows clients to request exactly what they need, avoiding over-fetching and under-fetching. Strongly typed schema-based queries.

Cons: Complex queries can impact server performance. All requests are sent as POST requests.

Features: Typically responds with HTTP 200 status code, even in case of errors, with error details in the response body.

GRPC (Google Remote Procedure Call)

Pros: Built on HTTP/2, it provides advanced features like multiplexing and server push. Uses Protocol Buffers, a language-neutral, platform-neutral, extensible way of serializing structured data. Efficient in terms of bandwidth and resources, especially suitable for microservices.

Cons: Less human-readable compared to JSON. Requires HTTP/2 support.

Features: Supports data streaming and bi-directional communication. Ideal for server-to-server communication.

Relationships in API Design

In an e-commerce setting, you might have relationships like the user to orders, orders to products, etc.