What makes an API irresistible? I'm not here to talk about the technical part, I'm here to discuss the planning and execution of your platform. There are a lot of completely resistible APIs out there, but nobody really sets out to create an API that makes developers sad. I know you want to do better, and I'm here to talk about how to craft your API to drive a delightful developer experience. To have a truly irresistible API.

But first, let's start with a story about an API going through its entire lifecycle. And then we can think about how irresistible it is.

Let's talk about a company that makes pizzas. Pizza Incorporated sells different pizzas through their website.

They're looking to expand our reach, so the CEO has a great idea! He's heard about all of these other companies with APIs and knows they are supposed to increase sales, so he says…

I want an API!

Many API projects start out just this way. I want an API! Why do you want an API? Because everyone else has one! Because… API. And money will fall from the sky.

So we're gonna build an API. Not exactly sure why, or who's going to use it, but let's do it. The project gets handed down to the product team

So now we're building our API, but what should it *do*? Well, everything!

And what should use it? Again, everything! You should be able to configure and order a pizza from your phone, TV, or refrigerator.

Rather than constrain the platform based on use cases, we'll just expose everything we have and let the clients decide what they want to do with it.

Now, faced with a project to build an API, and without any real use cases, the engineering team does the simplest possible thing. Exposes the database schema as a REST API. I call this the lowest common denominator API. Now we know for sure that the API is functionally complete, but how usable is it, really?

We have separate endpoints where there are separate items in the database. A simple query for information about a Hawaiian Bonzai pizza could require tens of calls to the API. It turns out that this is the same kind of interface they're using for the main website. So they say "It's good enough for the site". But is it, really?

Let's pause for a moment here and consider. It is simple to build a REST API. Most developers I know can do it in under 15 minutes. I have so many people ask me to review their API, then show me their functional spec. I will use standard HTTP methods. I will use a Node.js server. This is how timeouts and throttling will work. *yawn*

It's an Application Programming Interface, people. The interface is what it is. That's where the spec should be focused.

An API built in this way tends to grow organically. Since you can add new endpoints to the system without changing existing ones, small projects tend to crop up to add new functions. Different groups approach the same resources different ways, and the end product is frequently messy and chaotic.

Think about a potato, which has been left in the garage for a month. You come out to visit with your potato and find that it's sprouted all these funny looking things, all completely unrelated to each other. Nobody wants your potato API.

The Pizza Incorporated API was created without a central vision to guide development, resulting in a tangled mess.

Without a vision for the platform, internal teams are free to imagine their sections of the API individually. Different teams have different ideas about what should be exposed and how everything should work, and the whole process lacks cohesion.

The product teams working on the API aren't sure how their endpoints fit into the whole, which leads to confusion within the organization.

Now, if your own engineers and product managers can't articulate a vision for the API, if they don't know what use cases are supported and expected, how can you expect your customers to be successful using the API. They will stumble around your documentation looking for clues, and if integration is challenging they're likely to simply go elsewhere.

All of these combine to create a perfect storm, where your internal folks are building independent of each other and your customers aren't sure what to do with the system.

As a result, your API suffers from poor adoption and struggles to gain traction with customers and developers.

Now, here's the kicker. When creating an API it's tempting to think that since it's so easy to create, it doesn't need to show an ROI. But it's a product, and eventually someone from the C-Suite is going to come by and say "Why do we have an API anyhow?"

Given the poor adoption