Why I Decided to Write About API Design
My past three years were all about APIs. And I learned to care about this topic deeply. I also learned the hard way.
Like the time we shipped an API and realized we were returning data in plain text instead of JSON.
Plain text. Not the standard. Not even close.
We had to go back to every client and remediate. I'm sure they were thrilled. But at least we could bundle a new feature into the fix, so it wasn't all bad news.
Then there was the timezone incident.
We promised users 24 hours of their data. Sounds straightforward, right? Except we completely forgot that APIs run on Universal Time (UTC). So users in South America were getting less than 24 hours of data. Cue the pings, the calls, the rework.
These mistakes didn't kill us. But they cost time, trust, and energy.
So if you want to bring value through APIs and do it cleanly (build, ship, done), I'll give you the answers.
Why You Should Care About APIs (Yes, Even as a PM)
You might be thinking: "Why do I need to know about API design? That's engineering's job."
Fair. But here's the business case.
1.APIs generate real revenue.
→ 43% of API-first companies generate over 25% of total revenue from APIs
→ Some generate over 75%
→ Companies with strong API strategies see roughly 25% revenue uplift from integrations
2.APIs scale your product beyond your team.
→ Companies report 25 to 40% revenue growth from partner ecosystems built on APIs
→ Others build on top of your product. You get value without building everything yourself.
3.APIs are the backbone of modern systems.
→ Enterprises manage hundreds to thousands of APIs (averaging 354+, some up to 15,000+)
→ 83% of internet traffic is API-based
4.Well-designed APIs attract partners and compound growth.
→ API-first companies generate 2 to 3x more revenue than those without an API strategy
→ High-quality APIs create an ecosystem flywheel: more partners, more integrations, more value
And one more thing.
My architect once dropped this Jeff Bezos quote in a design review, and now I am dropping it here:
All teams will expose their data and functionality through service interfaces. Anyone who doesn't do this will be fired.
That was basically the beginning of Amazon Web Services.
APIs aren't a nice-to-have. They're how you let others multiply the value of what you've already built.
Quick Refresher: Types of APIs
Before we get into design, here's a simple breakdown of the most common API types.
→ REST APIs: The most popular. Uses standard web methods (GET, POST, PUT, DELETE). Simple, flexible, works for most use cases. If your team is building an API, it's probably this one.
→ SOAP APIs: The enterprise veteran. More rigid and structured. Common in banking, healthcare, and legacy systems. Heavier, but built for strict security and compliance.
→ GraphQL APIs: Lets the client ask for exactly the data it needs. No more, no less. Great when you have complex data or want to reduce the number of API calls.
→ Webhooks: Not a traditional API, but worth knowing. Instead of you asking for data, the system pushes it to you when something happens. Think: "Notify me when a payment fails."
Want a deeper dive? I covered APIs with a fun analogy in a previous newsletter. You can read it HERE.
How to Design an API Well
This is where it gets practical. Here are the most important principles, translated into PM-friendly language.
You don't need to code the API. But you should know what "good" looks like so you can push back, ask the right questions, and avoid the mistakes I made.
1. Keep it simple. If a developer can't figure out how to use your API in 10 minutes, it's too complicated. Clean endpoints. Clear naming. No surprises.
2. Be consistent. Same naming conventions, same structure, same behavior everywhere. If one endpoint returns dates as "YYYY-MM-DD," they all should. Inconsistency = confusion = support tickets.
3. Separate your concerns. Data, business logic, and presentation should live in different layers. This makes the API easier to maintain, test, and evolve.
4. Don't break what already works. When you release a new version, existing clients shouldn't break. This is called backward compatibility, and it's non-negotiable. (Remember my txt vs. JSON story? That's what happens when you skip this.)
5. Version your API. Changes happen. Version your API so clients can migrate at their own pace. Most teams use URL versioning (e.g., /v1/users, /v2/users).
6. Support pagination and filtering. Nobody wants to download 10,000 records when they only need 20. Let users request data in chunks and filter by what matters.
7. Handle errors clearly. When something goes wrong, tell the developer what happened and why. Good error messages save hours of debugging.
8. Take security seriously. APIs often handle sensitive data. Authentication, authorization, encryption. These aren't optional. Work with your security team early.
9. Document everything. If your API isn't documented, it doesn't exist. Include examples, use cases, and edge cases. Good documentation = adoption.
10. Design for scale. Think about caching, load balancing, and what happens when traffic spikes. Your API should handle growth without falling over.
11. Make it testable. Your team should be able to run integration tests, load tests, and regression tests easily. If testing is painful, bugs will slip through.
Print this list. Bring it to your next API design review. Ask your team: "Are we covering these?"
Practice Makes Perfect with Claude Code
The best way to learn how to design a good API is by actually doing it. And these days you don't need to wait for an opportunity. You can just build one yourself.
And I did it in 10 minutes.
Here's exactly what I did.
What you need:
→ A Mac or Windows computer
→ Node.js installed (free, takes 2 minutes from nodejs.org)
→ A Claude Pro subscription (Claude Code requires a paid plan. If you don't have one, you can still follow along to see what's possible.)
Step 1: Install Claude Code
Open your terminal and run:
sudo npm install -g @anthropic-ai/claude-code
Then create a project folder and start Claude Code:
mkdir my-api-project cd my-api-project claude
It will ask you to log in with your Claude account. Follow the prompts.
Step 2: Build the API
I gave it this prompt:
"Build a simple REST API using Node.js and Express for a feature prioritization tool. It should have endpoints to create, read, update, and delete features. Each feature has a name, description, and RICE score fields (reach, impact, confidence, effort) with a calculated priority score. Add basic error handling."
67 seconds later, I had a working API with six endpoints, input validation, and error handling. It even ran a test to make sure everything worked.
Step 3: Add Swagger documentation
I wanted a visual way to test the API, so I typed:
"Add Swagger UI documentation to this API so I can test all endpoints in the browser."
55 seconds. Done. I opened my browser, went to localhost:3000/api-docs, and I could test every endpoint right there.
The best part?
I kept talking to it. Like a conversation.
"Where is the data saved?" → It explained it was in-memory and offered to add a database.
"Yes, add SQLite." → It installed the library, rewrote the storage layer, and restarted the server. Data now survives restarts.
"How do I test this?" → It walked me through exactly what to do.
Why this matters for PMs
Look at the design principles I listed above. In 10 minutes, Claude Code applied several of them automatically:
→ Clear error handling (principle 7)
→ API documentation via Swagger (principle 9)
→ Input validation and consistent structure (principles 1 and 2)
→ Testable endpoints (principle 11)
I didn't ask for most of these. It just built them in.
You still need to know what good API design looks like so that you can validate what AI creates for you. But the gap between "knowing what good looks like" and "being able to validate it yourself" just got a lot smaller.
