Your API Knowledge is Incomplete Without These 16 Concepts
Understand 16 essential API fundamentals with clear explanations and quick examples to help you build better backend systems and ace interviews.
Hello guys, APIs are the backbone of modern software systems. Whether you’re building microservices, mobile backends, or large-scale distributed platforms, your ability to design, consume, and reason about APIs directly impacts system reliability, scalability, and developer experience.
In this guest post, Arslan Ahmad — Founder of DesignGurus.io and author of the popular “Grokking” System Design courses — breaks down the 16 must-know API concepts every software engineer should understand.
These are the principles that come up repeatedly in real-world architecture discussions and senior-level interviews, from API versioning and idempotency to rate limiting, pagination, and security.
If you want to design APIs that are not only functional but also scalable, maintainable, and production-ready, this guide will give you the mental models and practical knowledge you need.
With that, I handover to Arslan Ahmad to take you through the rest of the article.
APIs look complicated when you see big systems, but the core ideas behind them are surprisingly simple.
Once you understand these sixteen concepts, most API designs start to make sense. These ideas also come up repeatedly in backend and system design interviews, so learning them will help you explain answers confidently.
System Design Nuggets is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.
Let’s quickly understand each of these concepts.
1. REST
A REST API lets a client talk to a server using simple HTTP actions like GET, POST, PUT, and DELETE.
Each URL represents a resource, such as a user or a product.
The server responds with data formats like JSON.
REST is predictable because each verb has a clear meaning.
GET fetches data
POST creates something new
PUT updates existing data
DELETE removes it
This simplicity makes REST easy to learn. It also works well across browsers, mobile apps, and backend systems.
REST is one of the most commonly used API styles today.
Example
Imagine an online bookstore.
When you call GET /books, you get a list of books.
When you call POST /books, you add a new book.
When you call DELETE /books/10, you remove book number 10.
REST feels natural because every URL represents a resource and every verb represents an action.
2. GraphQL
GraphQL lets the client choose exactly what data it wants.
The client sends a query that describes the fields it wants, and the server returns only those fields.
It replaces multiple REST calls with a single flexible query.
This cuts extra data transfer and gives the client more control over the response shape.
GraphQL uses a single endpoint instead of many URLs. It also supports queries, mutations, and subscriptions.
Developers like it because it reduces round trips to the server. GraphQL is perfect for apps with complex or flexible data needs.
Example
A mobile app wants to show only a user’s name and profile picture, not their full profile.
With GraphQL, the client asks the server for exactly those two fields in one request.
This avoids extra data and makes responses smaller and faster.
It is perfect for apps where different screens need different shapes of data.
This reduces data transfer and makes mobile apps faster.
3. gRPC
gRPC is a high speed communication method used mainly between backend services.
It uses binary data called protobufs, which are smaller and faster than JSON. These messages are faster to send and easier to parse.
gRPC supports real-time streaming between clients and servers.
It is commonly used in microservice systems where performance matters.
The strong type checks make communication safer.
gRPC is not ideal for browsers, but great for service to service communication.
Example
Two microservices in a large system need to talk thousands of times per second.
Instead of using slow text-based JSON, they use tiny binary protobuf messages.
This makes communication extremely fast and efficient.
gRPC is ideal for service-to-service communication where speed matters a lot.
A recommendation service calling a ranking service can use gRPC to send thousands of requests per second with very low delay.
It sends data over HTTP/2, which helps with speed and streaming.
This makes it a good choice for service-to-service calls inside large systems.
4. API Gateway
An API gateway is the single entry point for all client requests.
Instead of clients talking to many services, they talk only to the gateway.
It handles:
• routing
• authentication
• rate limits
• logging
• request shaping
This keeps microservices simple because they do not deal with external traffic.
Gateways also allow centralized security.
If you update one rule, it instantly applies to every request. They help teams scale and manage large systems.
Example
A mobile app does not directly talk to ten different microservices.
It sends everything to a single API gateway.
The gateway forwards each request to the correct service and handles authentication, rate limits, and logging.
This keeps the mobile app simple and the backend organized.
5. Idempotency
Idempotency means sending the same request multiple times gives the same result. This prevents duplicate actions in case of retries.
For example, a payment request should not charge the user twice.
Servers use idempotency keys to track repeated attempts.
Idempotent operations make systems safer and more predictable. They are important when networks are unreliable.
Clients can retry without fear of causing errors. It improves the overall stability of the system.
Example
A user presses the “Pay Now” button twice because the screen froze.
Without idempotency, they might get charged twice.
With an idempotency key, the server knows both clicks refer to the same payment and processes it only once.
This makes APIs safe during retries and network problems.
6. Rate Limiting
Rate limiting restricts how many requests a user or system can send in a given time. It protects servers from overload or abuse.
Each user or token gets a limit such as 100 requests per minute.
When the limit is reached, the server rejects extra requests. This keeps the system healthy during traffic spikes.
Rate limiting is common in public APIs and SaaS apps.
It also helps control costs and prevent misuse of resources.
Example
A weather API gives every free user 100 requests per hour.
If a user sends 300 requests, extra ones are blocked.
This prevents abuse and ensures fair usage for everyone.
Rate limits keep the system stable when traffic spikes.
If a user sends more than allowed, the server blocks extra requests to protect the system.
7. Throttling
Throttling slows down clients that send too many requests instead of blocking them. It helps maintain performance without completely cutting access.
The server gradually delays responses to heavy users. This keeps critical services running smoothly.
Throttling is useful when you want fairness across clients. It prevents one client from overwhelming the system.
It is often used together with rate limits for better control.
Example
A client suddenly sends too many requests.
Instead of blocking them completely, the server starts slowing down responses.
The client can still use the service, but at a reduced speed.
This protects the system while keeping the user partially active.
8. Pagination
Pagination breaks large results into smaller chunks so the server responds faster.
Instead of sending thousands of records at once, the API returns a small page, such as 20 items.
Clients then request the next page using a token or page number. This reduces memory use and improves performance.
It also makes user interfaces smoother.
Without pagination, heavy responses can slow down apps or crash browsers. It is essential for list or search-based features.
Example
A shop has 50,000 products, but returning all at once would freeze the app.
The client loads the next page only when needed.
Instead of returning all 5000 products at once, the API returns:
• page 1: 20 items
• page 2: next 20 items
• page 3: next 20 items
This avoids slow responses and reduces memory load.
9. Versioning
Versioning helps APIs evolve without breaking older apps.
When a new change is added, the API might expose v1, v2, and v3.
Old clients keep using earlier versions while new clients use the latest. This avoids confusion and disruption.
Versioning allows teams to improve APIs gradually. It also gives time to migrate old systems. It is a key part of long-term API maintenance.
Example
Your API has v1 that returns name and price.
Later, v2 returns name, price, image, and reviews.
Old mobile apps keep using v1 without breaking.
Newer apps upgrade to v2 for richer data.
Versioning allows safe evolution of APIs.
Old apps keep using v1 while new apps use v2.
10. Webhooks
Webhooks let the server send updates to a client automatically.
Instead of the client repeatedly checking for new data, the server pushes events. The client provides a URL where updates should be sent.
Webhooks are used in payments, notifications, automation tools, and many integrations.
They reduce traffic and improve response speed.
They also make systems more event-driven.
Webhooks help apps react instantly when something important happens.
Example
Your app needs to know when a user completes a payment.
Instead of checking every minute, you give the payment service a webhook URL.
Whenever the payment succeeds, it sends you a message like “Order 101 paid”.
This makes systems event-driven and real-time.
11. HTTP Status Codes
Status codes tell the client what happened with a request. They help with debugging and error handling.
Common ones:
• 200: success
• 201: resource created
• 400: client error, like invalid requests or missing permissions
• 401: user not authenticated
• 403: user not allowed
• 404: resource not found
• 500: server error
Clear codes help clients understand problems instantly.
12. JSON
JSON is the most common format for API responses. It stores data in key-value pairs like { “id”: 1, “name”: “Alex” }.
JSON is easy to read, easy to parse, and supported everywhere. It works well in web browsers, mobile apps, and backend services.
JSON is lightweight and human-friendly.
Because it is simple, many APIs choose it as the default response format. It makes debugging and testing easier.
Example
A response like:
{
“id”: 7,
“title”: “API Basics”
}
is clear and easy to read.
JSON works in browsers, mobile apps, and backend systems.
It is the most common format for APIs because it is simple, lightweight, and easy to debug.
Almost every REST API uses it by default.
13. Authentication
Authentication verifies who is making the API request.
The system checks identity using tokens, passwords, or API keys.
If authentication fails, the request is rejected. This prevents anonymous or unauthorized access.
Authentication happens before any protected action is taken.
Systems often use tokens such as JWT or OAuth-based flows. It is the first step in securing an API.
Example
A user logs in and receives a token.
They attach that token to every request they send, proving who they are.
If the token is missing or expired, the server rejects the request.
Authentication ensures only real, verified users make API calls.
14. Authorization
Authorization decides what the authenticated user is allowed to do.
Even if the user is valid, they may not have permission for certain actions.
For example, an admin can delete users, but a normal user cannot.
Authorization protects sensitive features and data. It is usually controlled using roles or permission rules. This ensures users only perform allowed actions.
Example
After authentication, the server still checks what the user is allowed to do.
For example, an admin can delete accounts, but a normal user cannot.
Authorization protects sensitive actions and data.
It ensures users only do what their role allows.
• User A can edit only their own profile
• User B is an admin and can edit any profile
Both users are authenticated, but their permissions are different.
15. Timeouts
Timeouts prevent long running or stuck requests from blocking the system.
If a service does not respond in a set time, the request stops. This keeps resources free and protects the system from hanging.
Timeouts also help identify slow services.
They improve user experience by avoiding endless waiting.
They are important in microservice systems where delays can spread across services.
Example
A request to a slow database might hang forever.
To prevent this, the API stops waiting after a set number of seconds.
Timeouts free up resources and keep the system responsive.
They also help detect slow or failing services early.
16. Caching Headers
Caching headers tell clients and proxies how long they can store a response. This reduces repeated calls to the server.
For example, Cache Control: max age=60 means store the result for 60 seconds.
When the client reuses cached data, apps load faster and servers stay less busy.
Caching improves performance at low cost.
It is a key optimization technique for high traffic APIs.
Example
Suppose your API returns a list of countries that rarely changes.
By adding Cache Control headers, the browser can reuse the response for hours without calling the server again.
This makes apps load faster and reduces server load.
Caching is one of the easiest ways to improve performance.
Final Thoughts
These concepts form the foundation of modern API design.
Once you understand them, you can build faster, safer, and cleaner APIs. You will also explain your designs more confidently in interviews because these ideas show up in almost every backend challenge.
And, if you like this article then you can also checkout their popular System Design courses like Grokking the System Design Interview and Grokking the Advanced System Design Interview, both are great resource for anyone preparing for coding interviews.
You can also subscribe to their newsletter for free here
Other System Design articles you may like
 | A guest post by
|