API Design

Highlighted from System Design Interview Fundamentals, Chapter 5 

Focus on the Core

:brain: For a given API, focus on the input, output, and signature name. Ultimately, your goal is to ensure the API is clear, efficient, and solves the problem at hand.

• For example, Don’t focus on a protobuf and RESTul schema since that’s not the core of the question and is pretty wasteful. Only focus on it if the interviewer directly asks for RESTful design.

Few concepts to think about for your API:

Idempotency

Nicc source 

Preliminary: Concept of API resiliency:

• What is API resiliency? The API need to be able to recover from failure
• Normally, you just retry (could be with exponential backoff). (Practically good approach)
• However, the problem is, when we retry, how do we know previous run actually failed, instead of actually working in the background?
• An API that can deal with this is called idempotent API operations

An idempotent API operation is when a request can be retransmitted or retried with no additional side effect

• Another scenario: imagine the interviewer asks you to design an API to decrease the quantity of an item in an e-commerce order. Let’s say you have an order of quantity 3 and you want to make it 2. There are two ways you can do it:

decrease_quantity(order, quantity_to_decrease)
update_quantity(order, quantity)

• In decrease_quantity, you will call decrease_quantity(order, 1), and the item quantity will be decremented by 1. This API isn’t idempotent because if you call it multiple times, the quantity will keep decreasing.
• In update_quantity, you will update_quantity(order, 2), and the system will update the order quantity. This API is idempotent because no matter how many times you call it, the quantity will still be 2.

Idempotency is usually preferred since it’s possible to accidentally retry and result in unwanted behavior due to system and user errors However, idempotency isn’t always possible.

• For example, if you place an order multiple times, it is difficult to tell if it was a mistake or if you intentionally want to buy twice.
• You can introduce features to warn the user placing the same order within a short time frame, however, that is not considered idempotency.
• Some common way is adding a token to each API call.

Client vs Server Generated Data

When you have an input parameter in your API, you might be tempted to have the client pass as many inputs as possible. For example, a common data needed is timestamps.

• You can have the server generate the timestamp instead of the client.
• The client clock may not be in sync, or the client could be malicious, tampering with the timestamp field.

Efficiency

• Make sure your API is efficient. For example, if you are fetching a list of news feeds, make sure you don’t return every news feed for the user. You should think about pagination.

Correctness

• Correctness might sound obvious, but please make sure the API signature is true to its task, and the input and output are sufficient to satisfy the question’s requirements.