API Design — What Makes a Good API?

What makes one API a joy to work with while another becomes a developer's nightmare? This question sits at the heart of good API design - a skill that can make or break your effectiveness as a software engineer.

Every day, developers choose between competing APIs. They pick the payment processor that's easiest to integrate, the cloud storage service with the clearest documentation, and the AI service that works with minimal setup. These choices aren't random - they're driven by fundamental principles of good API design.

As a new engineer, understanding these principles will help you both choose better APIs for your projects and design better APIs for others. But what exactly separates the APIs that developers love from those they avoid?

Why Do APIs Exist?

Before we explore what makes APIs good, let's understand why we need them at all.

When you write code, do you build every function from scratch? Of course not. You use libraries, frameworks, and external services. APIs make this possible - they're the bridges that connect different pieces of software.

APIs Prevent Reinventing the Wheel

Think about the last time you needed to store images in your application. Did you build your own cloud storage system? Or did you use AWS S3's API?

If you chose S3, you leveraged years of engineering work with just a few API calls. Instead of spending months building infrastructure, you solved the problem that actually mattered for your business.

This illustrates the first purpose of APIs: they let us build on existing solutions. When you call OpenAI's API to add AI features, you're accessing billions of dollars of research and infrastructure through a simple interface.

APIs Enable System Integration

But APIs aren't just about accessing external services. They also solve another fundamental problem: how do different parts of your own system talk to each other?

Think about it - how does your frontend communicate with your backend? Through APIs.

APIs serve as contracts between system components. They define how different parts of your system communicate without requiring knowledge of internal implementations.

This separation enables powerful workflows. Frontend and backend teams can work simultaneously, as long as they agree on the API contract beforehand. This "API-first" approach has gained popularity because it enables parallel development and reduces integration headaches.

What Makes an API Truly Good?

Now that we understand why APIs exist, let's explore what distinguishes excellent APIs from frustrating ones.

Simple and Intuitive

The most important principle of API design is this: your API should make the developer using it successful.

If your API is confusing or hard to use, developers will either avoid it entirely or waste time fighting with it. Neither outcome is good.

This isn't just theory. In 2024, developer levelsio publicly criticized Google's AI API for being unnecessarily complex compared to OpenAI's single-command approach. The response was immediate and massive - thousands of developers shared his frustration.

This demonstrates the real impact of API usability, especially when the API itself is your product.

But what does "simple and intuitive" mean in practice?

Be Consistent

When your APIs follow consistent patterns, developers don't need to learn new conventions for each endpoint. They can predict behavior based on previous experience.

For example, if you have two deletion APIs, don't call one removeUser and another deleteProduct. Choose one naming convention and apply it everywhere.

Following established industry standards makes your APIs more intuitive. Developers immediately understand what a 404 status code means. They recognize what a 201 status code indicates. Use these conventions instead of inventing your own.

Use Clear, Descriptive Names

Your API names should communicate their purpose clearly. If someone needs documentation to understand what /api/v1/usr_mgmt_svc does, you've failed.

Here's a compelling example from Stripe's CTO: They built an API for "Issuer Fraud Records." During testing, developers couldn't understand the API's purpose because the name was too technical. They renamed it "Early Fraud Warning," and comprehension became immediate.

The lesson? Name APIs from the user's perspective, not your internal system's perspective.

Focused Scope - One API, One Job

Each API should have a single, clear purpose. If you struggle to name an API or explain its function in one sentence, you're probably trying to accomplish too much.

There's a guiding principle in API design: "When in doubt, leave it out." Adding features later is easier than removing them once developers depend on them.

Excellent APIs resemble excellent tools - they excel at one thing rather than attempting everything poorly. When designing APIs, resist the urge to add "just one more parameter" or "one more feature." Each addition increases complexity and reduces usability.

Ask yourself: Can you easily explain what this API does? Can you give it a clear, descriptive name? If not, consider breaking it into smaller, focused APIs.

What Really Matters for API Design?

Designing good APIs isn't about following rules - it's about empathy. Put yourself in the shoes of developers who will use your API. What would make their work easier? What would increase their productivity?

As a new engineer, you'll both consume and create APIs throughout your career. Understanding these principles will help you build better systems and make informed decisions about external API integrations.

Remember: a truly good API feels like a natural extension of the programming language itself. It should feel intuitive to use, not like a puzzle requiring solution.

What APIs have you used recently? How did they measure against these principles? More importantly, how will you apply these insights to the APIs you'll build in your career?

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.