Overview

The internet is not just websites for humans; it’s websites for computers. An API (Application Programming Interface) is a waiter. You (the app) ask the waiter for “Weather in London,” and the waiter goes to the kitchen (Server), gets the data, and brings it back. API Design is the art of making that menu easy to read.

Core Idea

The core idea is Contract. An API is a promise. “If you send me X, I promise to send you Y.” If you break that promise (change the API), you break every app that depends on you.

Formal Definition

The process of defining the interfaces by which one piece of software interacts with another. Styles: REST, GraphQL, gRPC.

Intuition

  • UI (User Interface): Buttons for humans.
  • API: Functions for code.
  • Bad API: A restaurant where the menu is written in invisible ink and the waiter speaks a different language every day.
  • Good API: Stripe. “Paste this 3 lines of code, and you can accept credit cards.” It just works.

Examples

  • REST (Representational State Transfer): The standard. Uses URLs like nouns. GET /users/123. POST /users. Simple and cacheable.
  • GraphQL: The challenger (from Facebook). You ask for exactly what you want. query { user { name, email } }. It saves bandwidth.
  • Stripe API: The gold standard of design. Clear documentation, helpful error messages, and consistent naming.

Common Misconceptions

  • It’s just code: It’s a product. Developers are your customers. If your API is hard to use, they will use a competitor.
  • Idempotency: If I send the same request twice (by accident), the server should handle it gracefully (not charge the credit card twice).
  • Versioning: v1, v2. How to upgrade the API without breaking old apps.

Applications

  • The API Economy: Companies like Twilio (SMS), Stripe (Payments), and Google Maps make billions just by selling access to their API. They are “Lego blocks” for other businesses.

Criticism / Limitations

  • Breaking Changes: The nightmare of every developer. “Deprecating” a field that everyone uses.

Further Reading

  • Lauret, Arnaud. The Design of Web APIs.
  • Fielding, Roy. Architectural Styles and the Design of Network-based Software Architectures. (The PhD thesis that invented REST).