Programming can be tough, especially when you’re starting out with a new language or trying to interact with a new API. It’s as if there are an endless number of strange procedures and functions with names you’ve never heard before, and all warranting special syntax.

This can be a serious distraction from the project you’re working on. In fact, you might even spend hours getting familiar with all the novelties before you even start moving forward on the task at hand.

That’s why, as an API owner, you should strive to build an API that gets developers feeling as comfortable as possible, as soon as possible — and you can do this by optimizing various aspects of the developer experience for your API.

The Importance of the Developer Experience

Before we get started on improving the developer experience for your API, we want to convince you of just how important it is (not only to the early stages of development but also throughout).

Think of every API as yet another tool in the developer’s toolbox. Just as with physical tools: not only do you need good ones, but you also need to be comfortable using them. And, as a very important addendum, the more comfortable you become using a tool, the more attention you can dedicate to the task at hand, and the better the results!

This is a really effective way to think about developer experience — in terms of comfort. Ask yourself:

• Are developers comfortable calling my API, in their chosen programming language, from their application?
• Are developers comfortable finding the functionality they need?
• Are developers comfortable using the output?

Of course, you can begin to satisfy these doubts — to improve your developer experience — by creating a ‘better’, more intuitive API , but a much easier way to do so is by helping your developers use and understand your API the way it is. More on that in a second.

What’s Your Favorite API?

Twilio and Stripe are routinely commended for quality DX. Discover 4 other quality APIs here.

In his presentation, Adeel Ali uses a clever thought exercise to illustrate the importance of the developer experience, asking the audience to name their “favorite” API.

For Adeel himself, the answer is Twilio, a cloud communications platform based out of San Francisco, which he had great memories of using in his developer days.
In signing up to the platform a second time, more recently, Adeel was greeted with an onboarding email for using the API — designed to help him “Get up and running in minutes” — full of links to helper libraries, quickstart packages, and various items of sample code.

At the time, he was “in no mood of doing any programming”, and simply wanted to see their reference material. Instead, he was met by page after page of interactive (the keyword in this sentence!) documentation, chock-full of workable code snippets and complete with dropdown boxes begging to know what programming language he was using.

Nowhere in sight was there the long and boring reference documentation we have come to know and expect from an API! Take a look for yourself.

As a result of Twilio’s bold introduction, Adeel was able to build his first “Hello World” in a matter of minutes. No wonder Twilio had once been, and still was, his favorite API!

Coming back to Adeel’s question, a member of the audience named Stripe their favorite, which comes with the same abundance of usage information, complete with tutorials, code samples, and getting started packages, with a choice of SDKs in over half a dozen languages.

While both APIs are praised in and of themselves, a large part of the favoritism does come from how highly they value developer experience, and how they succeed at optimizing it.

As software engineer Tejas Manohar writes in a comparison of payment APIs, “the best part about using Stripe is its ridiculously good documentation.” With that in mind, let’s see how we can import these great developer experiences into our own web API environments.

So, What Makes a Great Developer Experience (DX)?

Traditionally, API references are considered the cornerstone of developer experience. Unfortunately, creating extensive reference documentation costs a lot of money, takes a long time, and if done manually, documentation often requires rewriting after the most minor of changes.

Even then, there’s more to optimizing developer experience. Adeel identifies two key traits of ‘good’ APIs (in terms of developer experience):

1. They take care of redundant or repetitive tasks, leaving developers to focus on the creative process.
2. They speak the language of their developers – as he quotes Nelson Mandela:

If you talk to a man in a language he understands, that goes to his head, If you talk to him in his [native] language, that goes to his heart.

And although it’s an inherent idea in Adeel’s presentation, we should explicitly add a third:

3. They encourage a hands-on approach, allowing developers to start building as soon as possible.

Let’s see some concrete ways you can do the same with the developer experience for your API:

Taking Care of Repetitive Tasks

This is all about letting your developers focus on their solution, and not the means by which they’re building it. With that in mind, take care of repetitive tasks by:

* Providing complete SDKs, also known as helper libraries, which developers can download and begin using immediately
* Offering code samples, so developers can borrow from or straight-up copy common functionalities

(Notice these are both things Twilio and Stripe are doing. Some coincidence, huh?)

Speaking the Right Language

Again, this is about making the development progress as easy as possible for your developers. Speak the right language by:

• Providing SDKs and code samples in all of your supported languages.
• Ensuring that your documentation equally applies to and is just as relevant for all of your supported languages.
• Bonus: make sure your code sounds and feels “right” (maybe don’t ask the Python guy to create the samples for every language).

Encouraging A Quickstart

While we can’t speak for the majority, it’s arguable that most programmers learn by doing. Therefore, we must encourage developers to do the same with your API. Encourage quickstarts by:

* Providing complete quickstart or getting started guides
* Providing interactive playgrounds to sample API requests and responses
* Ensuring other reference materials are easily/readily available and well documented (especially with inline comments when it comes to code samples)

Improving DX: Current Practices vs. Smart Practices

As we mentioned earlier, most consider API references to be the foundation of developer experience. It’s no surprise then, considering that they’re written manually, that we spend hours working on them.

As Adeel points out, this status quo leaves API owners with four options when it comes to provisioning for developer experience:

• Put together an in-house team (which no doubt hurts the bank!)
• Outsource the project to one-time contractors (which makes it difficult to update, and still needs an in-house manager)
• Outsource the project to ongoing contractors (which still costs too much, and still needs an in-house manager)
• Leave it to the community (which comes with “no maintenance, no updates, [and] no support”)

No wonder, then, that this traditional approach comes with long release cycles, a high cost, and poorer quality (especially with inconsistencies between languages). Don’t worry though, we’ve come prepared with a clever way to improve developer experience for your API…

Smart Practices For Improving Developer Experience

There really are a number of ways to create a fantastic developer experience for your API without breaking the bank, and they all revolve around one thing: automation.

API Transformer is one of many tools for auto-generating developer resources.

At APIMatic, they suggest that you “maintain your API description, and leave the REST [to] automation”. That’s right – leave it to automation to build all your code samples, SDKs, and reference docs, and use the charm of a non-programming language sparingly, but effectively. This is, in fact, what their service aims to achieve.
Although not as comprehensive, Swagger UI is another popular solution for API documentation, based on the Swagger API specification.

What’s more, there are at least 30 tools that will generate your documentation for you. If you’re considering the automation route, do have a look around and see which packages line up best with your goals.

With the bulk of your developer experience taken care of by machines, it’ll be enough for one or two of your API architects to write some unique descriptions, and you’ll be set!

And, as a handy reminder: it’s also important to keep your documentation up to date. As our writer Art notes, “API behaviors must be thoroughly vetted … so why is that when it comes to API documentation, many people adopt the stance of ‘set it and forget it’?” For that reason, you may want to consider automatic testing solutions that keep your docs relevant for you.