Introduction
Ah, APIs—the love letters developers write to each other (sometimes in a cryptic language no one can understand). Whether you're crafting an elegant symphony of methods or unleashing a monstrosity of unreadable spaghetti code, this guide will help you design APIs that won't make your colleagues cry (or, at least, cry less). Let’s dive in!
Characteristics of Good APIs
1. Easy to Learn and Memorize
A good API should be so simple even your grandma could use it. If your API feels like it requires a PhD in rocket science, you’re doing it wrong. Let's say you're building a calculator API.
Bad API Example:
calculate(1, "plus", 2, { round: false, mode: "basic", verbosity: "low" });
"Uh, what? Why do I need to know the verbosity of a basic addition?"
Good API Example:
calculator.add(1, 2); // Ah, so simple even my pet goldfish gets it!
2. Leads to Readable Code
Readable APIs are the ones you can skim through without questioning your life choices.
Sarcastic Scenario: Imagine you’re debugging at 2 AM with coffee in one hand and despair in the other. Which code would you prefer?
Bad API Example:
const res = x.A(1, 2).B(3).C();
// What is A? What is B? Are we building a spaceship or solving math?
Good API Example:
const result = calculator.add(1, 2).multiply(3).getResult();
// Ah, now I know what I’m doing. I'm multiplying happiness.
3. Hard to Misuse
An API that’s easy to misuse is like a vending machine that eats your money. Let’s protect developers from themselves.
Bad API Example:
calculator.add("apple", "banana"); // Hmm, should this work? It does. But why?
Good API Example:
calculator.add(1, 2); // Only numbers allowed, sorry fruit enthusiasts.
And, of course, throw an error that screams:
"Invalid argument type: We accept numbers, not your grocery list!"
The Design Process
4. Know the Requirements
Before you write any code, ask yourself:
- What do users need?
- What do they actually need (not what they say they need)?
Example: If users need a Todo API, don’t build a rocket launcher API. Stay focused.
5. Write Use Cases First
Ever tried assembling IKEA furniture without instructions? Writing code without use cases is kind of like that, but worse.
Use Case:
// BEFORE implementation:
todo.addTask("Write blog").completeTask(1).deleteTask(1);
Now, build the API to match this. No extra fluff, no over-engineering.
6. Prepare for Extensions
Don’t create a rigid API that breaks the moment someone wants to add a feature.
Example of Extensible API:
interface Calculator {
add(a: number, b: number): Calculator;
subtract(a: number, b: number): Calculator;
withOptions(options: { precision?: number; mode?: "basic" | "scientific" }): Calculator;
}
7. When in Doubt, Leave It Out
Developers love adding features like it’s a toppings bar. But sometimes, the best topping is nothing.
Sarcastic Example:
// Bad API with unnecessary features:
todo.addTask("Cook dinner", { priority: "urgent", notifyVia: "pigeon", withEmojis: true });
Really? Emojis and pigeon notifications? Calm down.
Design Guidelines
8. Choose Self-Explanatory Names
Your API should be so clear even a 5-year-old could explain it.
Bad Example:
t.api(1, "xyz"); // What is this sorcery?
Good Example:
todo.addTask("Learn TypeScript").completeTask(1);
See? Clear, concise, and makes you look smart.
9. Avoid Abbreviations
Abbreviations are for Twitter, not APIs.
Bad Example:
usrMgmt.addUsr("John");
Is this a typo or code?
Good Example:
userManagement.addUser("John");
10. The Best API is No API
Sometimes, simplicity means not writing an API at all. Can you solve the problem without it? If yes, do that instead.
Example:
Instead of a custom fetchData API, just use:
fetch("https://example.com/data").then((res) => res.json());
Top comments (0)