What Makes API Design Its Own Discipline
You'll learn to
- -Say what an API is, and read a real request and response line by line
- -Explain why changing an API is riskier than changing code you control
- -Compare REST, GraphQL and gRPC by looking at the same request in all three
- -Know which protocol is the usual default for which kind of client
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
An API (Application Programming Interface) is the agreed way for one program to ask another program for something. When a ride-sharing app shows "your driver arrives in 4 minutes", it has asked a server a question through an API and shown the answer. API design is the craft of deciding what those questions and answers look like, and keeping them stable enough that thousands of apps you will never see can depend on them without breaking every time you ship a change.
An Analogy: The Wall Socket
A wall socket has a fixed shape. Any appliance with the matching plug just works, whoever made it and whenever it was bought. The electricity company can replace the wiring inside the wall as often as it likes. What it can never do is change the shape of the socket, because millions of plugs depend on it.
- -The socket's shape is the API contract: the addresses you call, the fields you send and get back, and the errors you may see.
- -The appliances are the clients: a phone app, a partner's integration, a script someone wrote three years ago.
- -The wiring inside the wall is your server code, which you are free to change.
- -Changing the socket's shape is a breaking change: every plug made for the old shape stops working.
A function signature in your own code is a contract between pieces you control and can change together. An API is a contract with clients you do not control and cannot force to update. That difference is what makes API design a skill of its own.
Reading One Real Request
Here is a complete exchange for a ride-sharing API. The first line is the question and the lines after the blank line are the answer.
GET /rides/812 HTTP/1.1
Host: api.example.com
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 812,
"status": "driver_arriving",
"driver": { "name": "Priya", "eta_minutes": 4 }
}- -GET /rides/812 is the method and the address: "fetch the ride whose id is 812".
- -200 OK is the status code, a short machine-readable summary of how it went.
- -The JSON after the blank line is the body: the actual data, in a shape both sides agreed on.
Now imagine a mobile app released two years ago that reads eta_minutes from this body. If the server team renames that field to eta, the old app finds nothing where it expects a number, and shows a blank or crashes. Nobody changed the logic. They changed the contract. This is why API design asks harder questions than ordinary code design: what must never change, what can safely be added, and how do you retire something without surprising anyone.
Three Protocol Families, One Question
There are three common ways to expose that same question. Look at how each phrases "give me ride 812". A round trip below simply means one request going out and one response coming back.
query {
ride(id: 812) {
status
driver { name }
}
}// ride.proto: the contract, compiled into client and server code
service RideService {
rpc GetRide (GetRideRequest) returns (Ride);
}
message GetRideRequest { int64 ride_id = 1; }- -REST, shown first: resource-oriented, built on HTTP methods and status codes. It is the default for public APIs and most service-to-service calls, because it is simple, cacheable and universally understood.
- -GraphQL: the client writes a query against one schema and gets back exactly the fields it asked for, in one round trip. It shines for products with many different frontends (web, mobile, third parties) that need different shapes of the same data.
- -gRPC: a binary, strictly typed format, meaning compact bytes rather than readable text, running over HTTP/2, a newer version of HTTP that can send many requests at once over one connection. It is the usual default between internal services, where speed and strict contracts matter more than readability or browser support.
This course follows the API Design Lab's own progression: REST fundamentals first (Acts 1 and 2), then GraphQL (Act 3), then gRPC and event-driven patterns (Act 4), then full systems that combine all three (Act 5). That is also the order engineers tend to meet these technologies in, from the most universal to the most specialized.
A recurring theme: the best protocol is never absolute. It depends on who the client is and what they need. Part of what an API design interview grades is whether you can name that trade-off instead of defaulting to whichever protocol you know best.
An interviewer asks: "Why would you choose GraphQL over REST for this product?"
"GraphQL is more modern and flexible, so it's generally the better choice."
"It depends on the client landscape - if we have several different frontends (web, iOS, a partner integration) that each need different slices of the same underlying data, GraphQL lets each one query exactly what it needs without us maintaining several REST endpoints or over-fetching. If we mostly have one client and a simple, cacheable resource model, plain REST is usually simpler to build, cache, and debug."
Why is API design treated as a distinct interview skill from HLD or LLD?
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!