CSE Roadmap

Core tier · about 3 hours · 9 parts

Part 2 of 9 · 3 min read

What an API is, and three common styles

The contract between a caller and a service, and the three ways teams usually write it.

Think of a restaurant menu. The menu lists what the kitchen can make and how to ask for it. The guest never enters the kitchen. The menu is the contract, and the kitchen may change its stoves without anyone noticing.

An API works the same way for software. The service offers a short list of operations, and callers use only that list.

API

An API (application programming interface) is the set of operations a service offers to other programs, together with the exact shape of each request and each reply.

Example: a weather service offers one operation, "get the forecast for a city", that takes a city name and returns a temperature and a date.

Two words appear in almost every sentence about APIs.

Client and server

A client is the program that sends a request. A server is the program that receives it and sends a reply. One program can be a client in one call and a server in another.

Example: a mobile app is a client of the shop's service. The shop's service is a client of the payment company's service.

A request and reply have to be turned into bytes to cross the network. That step has a name.

Serialization

Serialization is turning a structure in memory into a sequence of bytes that can be sent or saved. Deserialization is the way back.

Example: the record name = "Asha", age = 31 becomes the text {"name":"Asha","age":31} before it is sent.

Text formats such as JSON are easy to read and debug. Binary formats are smaller and faster to read by a machine. In one example in the book "Designing Data-Intensive Applications", a small record took 81 bytes as plain JSON text and 66 bytes in MessagePack, a binary form of JSON. The saving on such a record is small. The bigger gain of schema-based binary formats such as Protocol Buffers comes from rules about change, which Section 6 covers.

The book "Understanding Distributed Systems" names the three styles most used for request and reply calls.

Style Typical use Message format Main strength
REST over HTTP Public APIs, browsers, mobile apps Usually JSON Simple, cacheable, easy to try with a browser
gRPC Calls between a company's own services Protocol Buffers (binary) Fast, strict schema, generated code
GraphQL Apps with many screens that need different data JSON, shaped by the caller's query The caller asks for exactly the fields it wants

RPC

An RPC (remote procedure call) makes a call to another machine look like a call to a local function. gRPC is a popular RPC framework.

Example: the code shop.getPrice(42) runs on the server, and the result comes back as if the function were local.

The book's rule of thumb: internal calls between services in one organisation tend to use a fast RPC framework such as gRPC. Public APIs tend to use REST. This page treats REST in detail, because it is the style an interview asks about most, and then looks at the other two.

Read it as

An API is a promise. The server may change everything behind it. It may not change the promise without warning.

Check yourself:

  • Which side of a call is the client, and can one program be both?
  • Why might a company use gRPC inside and REST outside?