Don't Just Write APIs — DESIGN Them!

This post is heavily inspired by the paper published by Jasmin Blanchette on June 19, 2008, titled "The Little Manual of API Design".

You can read the paper here: https://github.com/papers-we-love/papers-we-love/blob/master/api_design/api-design.pdf

What Exactly Is an API?

According to Wikipedia:

An Application Programming Interface (API) is a set of functions, procedures, methods or classes used by computer programs to request services from the operating system, software libraries or any other service providers running on the computer.

An API is essentially the building block of any application, and it is extremely important to design it deliberately and with care.

Below is a small guide to help you design better APIs.

A Thought to Begin With

Software is built on abstractions. Pick the right ones, and programming will flow naturally from design; modules will have small and simple interfaces; and new functionality will more likely fit in without extensive re-organisation. Pick the wrong ones, and programming will be a series of nasty surprises.

— Daniel Jackson

Easy to Learn and Memorize

An API should be intuitive.

Suppose you have an API to get apples from a tree:

apples();

This is ambiguous. A developer has no clear idea what it does.

A better approach:

getApplesFromTree();
fetchApplesFromTree();

These names are self-explanatory and reduce cognitive load.

A real-world example is React lifecycle methods:

componentWillMount();
componentDidMount();

Readable Code

❌ Bad Code Example

const capitalizeAndAddDotAtTheEnd = (word) => {
  return word[0].toUpperCase() + word.slice(1) + '.';
};

✅ Good Code Example

const capitalizeFirstLetterOfWordAndAddDotAtTheEnd = (word) => {
  const firstLetter = word[0];
  const remainingLetters = word.slice(1);

  return firstLetter.toUpperCase() + remainingLetters + '.';
};

Both functions do the same thing, but the second is far more expressive.

Key principle:

Code is written once but read many times.

Favor readability over micro-optimizations in most cases.

Hard to Misuse

A well-designed API should guide developers toward correct usage.

capitalizeAndAddDotAtTheEnd();

It’s unclear whether it expects a word, sentence, or paragraph.

Now compare:

capitalizeFirstLetterOfWordAndAddDotAtTheEnd();

This makes the intent explicit.

Easy to Extend

Think ahead when designing APIs.

❌ Poor Design

getOranges();
getApples();

✅ Better Design

getFruits(type);

Example:

getFruits('mango');

Resources and Further Reading

https://github.com/papers-we-love/papers-we-love/blob/master/api_design/api-design.pdf
https://www.youtube.com/watch?v=aAb7hSCtvGw
https://frontendmasters.com/teachers/kyle-simpson/code-is-for-humans/

Final Thoughts

APIs are not just technical constructs — they are interfaces for humans.

Design them with clarity, intent, consistency, and extensibility.

Don't Just Write APIs — Design Them!