The API Developer Experience

3 myths, 3 suggestions, 3 facts

We’re moving toward a world where we're getting to know our devices better. We're talking to them and they are talking to us, we are exchanging information. We have never felt this close to our devices, they have never felt this personal. From health monitors to drones, thermostats to smartphones; we are enjoying every bit of what they add to our lives.

More and more devices will be added to our lives; with an ambition of enriching life's quality. While this is great from a technology and consumer standpoint, it poses a big challenge for us - the IT folks. One side we have this complex IT system landscape and on the other side the numerous devices to be served. How do we cope with this complexity? APIs can help bridge the gap between IT systems and devices.

Let us take a look at the API Value Chain. An API exposes a business asset. This API is consumed by one or more Apps. And it is through these Apps, the end customer experiences your services.

Figure 1 - API Value Chain

It is fairly obvious that these apps are crucial in not only bringing value to the end customer but also to the success of your API. Yet, the Developer who builds these beautiful apps is often neglected when it comes to building APIs.

I'd like to highlight 3 common myths in teams building APIs:

• Myth 1: We'll think about the developer experience later. It's for public APIs anyway.
• Myth 2: Developers are bound to love our API. I mean, what's not to like?
• Myth 3: We know what's best for our API. We don't need developers telling us what to do.

An attitude like this won’t get you far. With more than 12000 public APIs (on the Programmable Web) to choose from, your API will be like a great film in whom no one is interested. The purpose of this article is to give a different perspective that will help you build APIs loved by Developers.

Suggestion 1: Treat your API as a Product

An API is not just a software interface. It is an interface to your business asset, your services, your organization. It should be easy to consume and build beautiful apps with. Hence, treat it like a product and do whatever it takes to make that product a success.

For example

• Give your API a URL; make it discoverable. If it is a public API, register it at http://apis.io/
• Have clear Terms of Service (TOS). Do not leave these up to the Legal Department to write down. It is your product. Write them down yourself.
• Ensure easy sign up. There is nothing worse than a hundred clicks just to get an API key.
• Document your API thoroughly. Documentation, though under-rated is read by anyone who wants to consume your product. Make sure the documentation up to date.
• Software Development Kits (SDKs) are great to have people develop on your API.
• Make it easy for developers to write apps with your API. Provide Hello World sample apps.
• Announce releases and have release notes.
• Provide Sandboxes for developers to test and play with your API.
• Honor feedback and provide support. 

Suggestion 2: Ensure ease of use

An API that is not easy to use will most certainly not be used. Make an effort to keep it intuitive for an App Developer. Remember that an App Developer may not always understand your business.

For example

• REST is best; don’t make up your own conventions.
• Stick to JSON for representing data. JSON is by far the most popular representation for JavaScript based clients.
• Use HTTP; and all of it (status codes, verbs and all). Do not design your own standards.
• Use Hypermedia to enhance navigability of your API. If the data is the state, hypermedia is the state transfer. Both aspects are equally important when it comes to a great API.
• Use OAuth 2 for authentication.
• Provide curl Scripts to access and explore your API.
• Think about different types of clients that might use your API. Mobile clients, screen-less clients.
• Never break existing clients. Never make breaking changes.
• A great API knows its audience. Do not expose internal jargon.

Suggestion 3: Welcome Innovation

Creating an API for a specific client and for a specific need may be a good starting point, but it’s certainly not the destination. Dream big! A great API has immense potential. To tap this potential, you need to welcome innovation. This innovation will most likely with come from the consumers of your API.

For example

• Developers are not stupid. Get to know them.
• Invite feedback. Use it as a boost to enhance your API.
• Organize Hackathons with your consumers. Together, special things happen.

I sincerely hope that you will take these suggestions into consideration when you build your next API. I’d like to conclude this article with the 3 facts which serve as a reminder that an API is more than just a software interface.

• Fact 1: An API is only as valuable as the Apps built with it.
• Fact 2: This makes the API Developer Experience crucial.
• Fact 3: Like any good experience, the API Developer Experience must be designed.

A great man once said, “Design is not just what it looks like. Design is how it works”. So Design like you give a Damn! Design like you give a Damn. Design like you give a Damn.