Introduction

Some APIs are functional only.

You make a request.

You receive an answer.

Well done.

And then there are the APIs that developers love to work with.

Stripe is often mentioned in that latter category.

What’s interesting about Stripe isn’t just the financial infrastructure it provides.

It’s the approach that the company took to the developer experience around that infrastructure.

An API isn't a technical interface for developers.

It’s all part of the product.”

Confusing API's lead to frustrating developer experience.

Developers are able to build a lot faster if it’s predictable, well-documented, and built around real workflows.

Stripe is a particularly good example to study because it has public documentation that shows many of the design ideas that developers stumble upon when they are adding payment functionality.

In this article, we will look at those principles from a developer and product perspective, not as a statement about how KarmaKoders works with Stripe.

Stripe began as a developer problem

Founded in 2010 by brothers Patrick and John Collison.

Its broader goal was to simplify online payments for businesses.

That sounds easy.

But accepting payments is much more than just putting a credit-card form on a webpage.

Developers have to cope with:

·       payments

·       customers

·       payment options

·       refunds

·       subscriptions

·       disputes

·       authentication

·       webhooks

·       failures

·       asynchronous events

So the API needs to be a complex financial system that developers will actually understand.

The Product Experience Becomes The API

Let’s say you are adding a payment provider.

You don’t want to know every internal system behind it.

You'd like to know:

How do I get a customer?

How do I make a payment?

How do I know if it worked?

What do I do when I mess up?

How can I get a refund?

A nice API takes such complex operations and makes them understandable building blocks.

That’s one of the big learnings from Stripe.

Resources should be real-world things.

A good API is usually based on a good resource model.

Instead of creating arbitrary endpoints around database tables, think in the terms that the developers understand.

For a payments platform, those concepts could include:

·       customers

·       payment_intents

·       charges

·       refunds

·       subscriptions

·       invoices

Names matter.

They build a mental model from them.

If the API terminology is confusing, everything built on top of it is harder.

Consistency Reduces Developer Friction

Imagine one endpoint is using:

customer id

other uses:

clientId

another usage:

user_identifier

Though all three are referring to similar ideas.

The API is intended to function.

But now developers have to remember exceptions.

Consistent naming takes that mental load off.

The same principle applies to:

·       endpoint structure

·       parameters

·       response formats

·       error structures

·       authentication

·       pagination

Good API design is often boring.

That's a nice compliment.

The API has built-in documentation.

As a developer you shouldn't have to reverse engineer your API.

Good documentation should answer:

What is the function of this endpoint?

What parameters are needed?

How is the reaction?

What errors can occur?

What happens then?

Stripe’s docs have always been very code heavy and focused on how to build integrations, which is a big part of the dev facing product experience.

The lesson for API builders is clear:

Documentation is not sales literature.

It is a sort of it.

Code Examples Make Learning Easier

Developers learn differently than typical software users.

An API explanation paragraph is useful.

A working code example can be even more useful.

Examples:

Design a customer

↓

Produce payment

↓

Deal with the reply

Seeing how the pieces connect helps the developer understand the flow faster.

This is especially the case for SDKs and developer platforms.

Happy Paths Are More Important Than Error Messages

All API demos work perfectly.

Real applications don’t.

Payments are not processing.

Cards are refused.

The authentication expires.

Requests time-out.

Actions can be canceled.

Third party systems go down.

Developers need to know what went down.

A good error should ideally help answer:

What’s happened?

What brought it on?

Is it repairable?

“Should I try again?

A vague;

“Something went wrong.

is not very helpful.

Idempotency is an important API concept

Payments are a particularly important problem.

Let’s say a customer clicks:

Salary

The app requests.

Then the network connection is not stable.

The front end doesn't know if it processed the payment.

Should it retry the request?

It is dangerous if you do it twice and there is another payment.

Here is where idempotency comes in.

An idempotency key can be used to allow a system to recognize duplicate attempts and avoid accidentally performing the same operation more than once.

It is a powerful idea for APIs that work on data where duplication matters.

Ponder failure before success

Good API design asks:

What happens if something goes wrong?

For a payment system:

Successful payment

is a single State.

You might also have:

·       payment failed

·       requires additional authentication

·       payment pending

·       payment canceled

·       payment disputed

Those states must be clearly indicated on the API.

This is an important lesson for any API developers who do a lot of workflow work.

Everything Changes with Asynchronous Events

Not everything important happens in the original API request.

For example, a payment status can be changed later.

A system needs a way to inform the application:

“Something’s happened.”

That’s where webhooks come in handy.

Rather than asking all the time:

“Was the pay different?”

Something happens and the app can listen for an event.

Here’s an example:

Payment event

↓

Webhook

↓
Your backend

↓

Change order

↓

Contact customer

This event-driven pattern is very broadly useful beyond payments.

Webhooks Must Be Designed Carefully

It’s not the end of the problem when you get a webhook.

Your system should take into account:

·       Event ordering

·       retries

·       authentication

·       processing failures

·       duplicate events

·       idempotence

A webhook handler must not assume that:

“Once in this event.

That assumption is rarely warranted in distributed systems .

Design for duplicates and retries.

Versioning Safeguards Existing Integrations

Once the developers build on the API, it’s hard to change it.

Imagine thousands of applications rely on:

GET /customers

You change the structure of the answer suddenly.

Existing applications may break.

API evolution thus needs discipline.

As an API grows, versioning and backward compatibility and deprecation strategies become important.

This is not a Stripe issue.

It is a basic problem for any serious API platform.

The Ability to Abstract

One fascinating product decision at Stripe is that developers don’t need to know all the details of the underlying financial infrastructure.

The API is an abstraction.

The developer works with concepts like:

subscriber

purchase

rebate

membership

instead of dealing directly with all underlying financial processes.

Good abstractions hide the complexity you don’t need to know and preserve the control you do.

But Don’t Abstract Too Much

There is a balance.

“A frustrating API is one which hides everything.

Developers need to have control eventually.

For instance:

Where did all my money go?

Why was it shut down?

What authentication step is needed?

What does this status indicate?

A good abstraction does not conceal important information.

It hides the complexity of implementation.

APIs Should Be Built Around Workflows

One of the biggest mistakes in API design is to think about it purely in terms of database operations.

For instance:

POST /makePayment

may work in practice.

But what must the developer do before and after that request?

The workflow might be:

Generate client client

↓

Create a Payment Intent

↓

Gather payment information

↓

If you need to,authenticate

↓

Confirm payment

↓

Receive event

↓

Update order

An API should help developers understand the entire workflow, not just individual endpoints.

Developer Experience Is a Business Edge

But here’s the bigger lesson.

A developer who can build your product in:

one afternoon.

may prefer your service to that of a competitor who takes:

three days to,

to comprehend.

This impacts:

·       adoption

·       cost of maintenance

·       speed of integration

·       customer satisfaction

·       recommendations of developers

For products that are developer-centric, the design of the API can directly affect business growth.

SDKs Can Make APIs Even More Easy

Developers don’t always need to be writing raw HTTP requests.

SDKs may include language-specific interfaces.

For example:
javascript
python
Ruby

PHP

and more”

The API is still the underlying contract. SDKs just make it feel more natural in the developer’s existing environment.

This can help cut down on friction during integration.

Testability is important

Developers need a safe place to try things out.

You don’t want someone running payment function tests with real money.

So a good API platform needs to provide mechanisms for development and testing.

The general principle is:

Make the easy way safe.

Developers should be able to test the following:

·       successful

·       payments

·       failures

·       refunds

·       webhooks

·       edge cases

prior to production.

Security Is Not an Afterthought

Financial APIs naturally have very strict security requirements.

But the larger lesson applies to all APIs.

Consider this:

·       authentication

·       authorization

·       secret management

·       encryption

·       rate limiting

·       input validation

·       audit logs

·       monitoring

API is an attack surface.

Don’t sacrifice security for convenience.

Good APIs are intuitive

Developers are big fans of predictability.

If an endpoint returns:

{ "status": "active", "id": "123" }

and another comes back:

{ "id": 123, "state": 1 }

The API is more difficult to work with without a strong reason.

Consistency is not exciting.

But it is this consistency that makes APIs scalable for the developer.

Best APIs Reduce Questions

Imagine a developer building your service.

A well designed API should have them asking less questions.

More like this:

What does this field mean?

as their documentation tells them.

Rather than:

“What if it doesn’t work?

the error is API specified.

Rather than:

“When do I know this changes?”

there is an event/webhook system.

I want to say:

“What if I try once more?”

the API is conceptually clear

Excellent developer experience.

What Stripe Can Teach Developers

1.     Design with real-world scenarios in mind

Don't reveal your internal database just because it's convenient.

Wrap an API around ideas that developers actually understand.

2. Treat documentation as part of development process

The documentation should grow with the API.

This is not something to write six months post-launch.

3. Designing failure states

Your API should describe what happens when things don’t go as planned.

4. Make dangerous operations secure

Idempotency is a great example.

"If something can be done twice by accident, you need to design mechanisms to mitigate that risk."

5. Move beyond requests and responses

Real-world applications are asynchronous.

Events and webhooks are just as important as normal API calls.

6. Prioritize developer experience

Don't just ask:

“Is the endpoint working?

Question:

“Can a developer read this and work it out without having to contact us?”

Now that’s a much better API design question.

What Founders and Product Teams Can Learn

API design is not a backend problem.

If your product relies on integrations, your API can be part of the product strategy.

A good API enables:

·       partners to integrate

·       customers to automate workflows

·       developers to build extensions

·       internal teams to connect systems

Thus, the API can be a distribution channel.

That’s why founders should care about developer experience even if they aren’t developers.

Conclusion

Stripe is a good case study for API design because it illustrates a broader point:

Complex infrastructure should not equal complex developer experiences.

Good API design can help to make complex systems easier to understand by providing:

·       clear resources

·       consistent naming

·       predictable behavior

·       useful errors

·       strong documentation

·       safe retry mechanisms

·       event-driven work flows

·       valuable abstractions

The lesson here is not to copy Stripe’s API.

Its to understand the rationale behind developer friendly APIs.

API is not just the plumbing when you are building software that needs to communicate with other applications.

This is part of the product.

We build APIs at KarmaKoders to connect web applications, mobile apps, third-party services and internal business systems. We focus on maintainability, security and developer experience.