API Design — Optimizing Your Team's API Design Process

In previous articles, we discussed API Design — What Makes Good API Design? and API Design — How to Design Stable, Compatible APIs.

But here's a question: What if you're working toward becoming a senior engineer and want to improve your entire team's API quality? How do you make that happen?

Think about your current team for a moment. When someone needs to design an API, what actually happens? Do they just start coding? Do they have a process, or does everyone wing it differently?

This article shifts perspective to the senior engineer level, focusing on API design processes, design guidelines, and documentation. As you read, consider which aspects your team could improve and how you might drive those changes.

Why Process Matters for API Design

Before diving into specific processes, let's think about this: Why would you need a structured approach to API design anyway?

Here's the thing - APIs exist to serve the people who use them. They solve problems and provide functionality. But here's what often happens: developers design APIs from their own perspective, thinking about what's easy to implement rather than what's easy to use.

This is where process becomes crucial. A good process ensures you're building something people actually want to use, not just something that works.

Understanding User Needs

So where should you start? Let's think about this step by step.

If APIs exist to serve users, what's the most logical first step in designing one? That's right - understanding what users actually need.

This might seem obvious, but how often does this actually happen in practice? Too often, API design starts with "we need to expose this database table" or "we need to make this internal function available." But what if we flipped that around?

Working Backward from Users

Stripe's former CTO David Singleton shared a principle that's worth paying attention to: working backward from the consumer of the API. Instead of starting with what you want to build, you start with who will use it and why.

But how do you actually do this? Here's where it gets practical:

Stripe's API developers participate in user research. They sit down with actual API users and watch them integrate the API. They observe where users get stuck, what confuses them, and what feels natural. They collect feedback through multiple iterations before officially releasing anything.

Think about this approach for a moment. What would happen if you tried this on your team? Instead of building an API and hoping people use it correctly, you'd be building something you've already seen people successfully use.

Here's another key insight: they often let users try connecting to mock APIs before implementing the actual functionality. Why might this be valuable? Because if the design is confusing or missing important use cases, you discover this before spending weeks building the wrong thing.

Listen, But Don't Just Follow

Now, here's an important nuance: when you talk to users, don't just do exactly what they ask for. Why not?

Users often see only their immediate problem. As an API designer, you need to think broader. What's the deeper need behind their specific request? What other use cases might emerge? How might their needs evolve?

Your job is to understand the real requirement beneath the surface request.

The Design Phase

Once you understand user needs, you should be able to clearly answer two questions:

1. What do users want to accomplish with this API? (Why do they need it?)
2. What design approach will make this feel intuitive to them? (How should you build it?)

If you can't answer both questions confidently, what does that tell you? It probably means you need to spend more time in the discovery phase.

But let's say you can answer both. Now what?

Getting Cross-Team Input

When you move into actual design, who should be involved? Just the development team?

Well-structured teams typically bring in platform engineering, developer experience, and security teams at this stage. Why these specific groups?

Platform engineering ensures your API fits well with existing infrastructure. Developer experience teams think about how this API will feel to use alongside other APIs. Security teams identify potential vulnerabilities before they become problems.

This isn't about slowing down development - it's about catching issues early when they're cheap to fix rather than expensive to retrofit.

Taking Action on Your Team

So how do you actually improve your team's API design process? Here are some practical steps:

Start with user research: If your team doesn't currently talk to API users before building, suggest introducing this step. You don't need a complex process - even informal conversations with users can reveal valuable insights.

Create a design review process: Establish a small group of reviewers who can provide feedback on API designs before implementation. Include people from different technical backgrounds - security, platform, frontend, backend.

Document your decisions: Keep track of why you made specific design choices. This helps future team members understand the reasoning and maintains consistency.

Test early and often: Set up ways to get feedback on API designs before full implementation. This might mean creating mock endpoints or prototypes that users can experiment with.

Which of these resonates most with your current team's needs? Where could you start making improvements?

Remember, the goal isn't to create bureaucracy - it's to build APIs that users actually want to use. The right process should make good design easier, not harder.

Support ExplainThis

If you found this content helpful, please consider supporting our work with a one-time donation of whatever amount feels right to you through this Buy Me a Coffee page, or share the article with your friends to help us reach more readers.

Creating in-depth technical content takes significant time. Your support helps us continue producing high-quality educational content accessible to everyone.