Developer experience is a vital component of API design. The best developer experience will result in a better, stronger, more useful API, and by extension, a better, stronger, more useful end user experience.

While developer experience is very much a subjective thing that is highly dependent on the developer consumer, there are nonetheless some recurring positive elements that successful APIs with good experience share.

In this piece, we’re going to discuss exactly that. We’ll outline four qualities that an API should have as part of a comprehensive developer experience, and we’ll look four specific web APIs that boast these qualities.

What Makes a Good Developer Experience

As has already been said, there are subjective elements of each API that a developer might find more helpful than another developer would. That being said, there are some objective qualities that APIs should strive for.

Communication

Prime of these qualities is being communicative. An API is only as good as its leveraged implementations – in other words, the best API in the world is worthless if it can’t be implemented. Accordingly, a good API should boast comprehensive and communicative documentation and code examples.

Such documentation should clearly explain common implementations in a variety of languages, as well as discuss the inner workings of the API in terms of exposed functionality that might be necessary.

A communicative API should:

• Provide methods of education for a variety of learning styles that document common functions and use cases.
• Boast sufficient reference material without relying too heavily upon it.

Responsiveness

Though documentation is highly valuable, the API itself should be able to be responsive to input itself, instead of demanding a developer utilize a lookup sheet or reference table. An API that is responsive, then, should make itself and its functions clear to the developer when utilizing it, exposing flaws, errors, and issues as they arise.

A responsive API should:

• Allow the functions and errors of the API to be understood without demanding extensive use of documentation materials.
• Communicate in plain language with the user and their system, avoiding unnecessary obfuscation and complexity.

Interactivity

An important quality of an API and its documentation is that it should be interactive. The users and developers who utilize an API are not going to be static – they’re going to have interactive, dynamic questions and requirements, and as such, an interactive API will boast much greater ease of adoption, a greater amount of understanding, and an overall better developer experience.

An interactive API should:

• Provide live testing facilities to enable exploration and discovery. This can be done using playgrounds or even virtualized environments.
• Enable developer consumers to interact with the system directly, rather than learn about the system and then utilize it.

Guidance

Documentation is one thing, but guidance is entirely another concept. Being able to predict common use cases and discuss the code base in its entirety is extremely valuable as it reveals the mind of the developer.

While having a solid reference base is useful, it does nothing to expose why things function the way they do – there’s no insight into the thought processes behind specific use cases. A system rooted in guidance connects the API provider directly to the developer user, exposing intent, design concepts, and purposes behind each solution.

A guided API should:

• Educate the developer as to how an API functions without holding their hand directly through each process. In other words, it should teach, not instruct.
• Provide a wealth of resources for the user to approach as time and function requires.

Heroku – A Communicative API

Heroku is a perfect example of a communicative API. Their documentation is clear, up to date, and very comprehensive. The documentation itself is split up into logically divided sections that move from least complex to most complex, and each section progresses in a likewise fashion. This mimics the natural learning path, and accordingly makes it much easier to understand complex topics in chunks rather than trying to gather a holistic understanding from the get-go.

Importantly, Heroku’s documentation is some of the most extensive of the examples on this list. Extensive documentation, including examples, is provided for Node.js, Ruby, Java, PHP, Python, Go, Scala, and Clojure, covering the large spread of the most popular languages for Heroku’s user base.

This is all collated in a “Learning” center that helps teach some specific functionalities of the Heroku API in the given languages, helping developers locate specific data relevant to what they want to do. There’s also a powerful companion section called “Reference” that focuses heavily on reference material for on-the-fly work. While this is great for developers creating their API, this is also extremely powerful for debugging systems and identifying specific issues.

Most importantly, however, is the “Getting Started” section on offer. The section offers some key pieces of code, explanations, and overall suggestions for implementing Heroku in your given situation. For all of these reasons, the Heroku API is extremely communicative, and boasts quality developer experience.

Heroku developer center provides quality developer experience

Zalando – A Responsive API

Zalando library implements the IETF HTTP API error handling as standardized in RFC 7807.

Zalando is a very function-specific API designed to implement application/problem+json Content-Type, which is defined in RFC 7807. This RFC is an implementation of a “problem detail” definition, which is a standardized way to carry machine-readable details for failures and errors in the HTTP response.

What this functionally means is that HTTP APIs, and in this case Zalando, can avoid the need to make their own custom HTTP error responses, and instead use a standardized methodology. In this way, Zalando is extremely responsive, in that the error is immediately understandable. There’s no reason to look up an error code, check the reference material – the API is responsive to the error and describes the error directly.

This is extremely powerful, and while the rest of the documentation can be somewhat complex to those unfamiliar with GitHub, the fact that the API describes its own errors is hugely powerful.

Marvel – An Interactive API

Marvel is one of the most interactive APIs that a developer could ask for. Every aspect of the API, from the way it fetches characters to the way a comic ID is called, is testable directly from an interactive panel of the most common public calls. The tester automatically integrates your API key, filling it for you for each test call.

Once a test call is made, a set of implementation notes, a response class model and model schema, a series of parameters, and a listing of error status codes are provided. This level of interactivity with testing solutions is rare, and the ability to directly try out the API and test permutations is extremely powerful for two main reasons.

First, this aids in the development of applications that utilize the Marvel API. In exposing the functionality of the API in a testable format, the developer can begin to understand the internal structure and schema of the API and its myriad functions. This overall improves the development experience, increasing code confidence and decreasing overall complexity.

Second, this aids in error discovery. Being able to find whether or not the error is occurring internally or as the result of a given parameter is very valuable, and leads to a more secure API that is more predictable, more dependable, and more extensible.

Marvel’s interactive API documentation

Scale API – A Guided API

For an example of a guided API, we’ll turn to Scale API. While Scale API has the standard share of documentation pages and offerings, the real appeal here is that each documentation section is accompanied by a sidebar of extensive explanation and examples. While the documentation, like the API, is rather spartan, the fact that each function is well-explained is extremely helpful, and guides the developer towards expected functionality.

Code examples on the right column help guide implementation of the Scale API

Even more important than the explanation of basic function, though, is the inclusion of what can be expected with a bad response. By delineating what a bad response looks like and what the developer can expect, users are given systemic understanding upon which to develop.

It must be stated as well that the Scale developer portal is aesthetically pleasing. While the look of documentation is not necessarily a determinate factor of quality, when the documentation itself is high quality, good graphical design only bolsters confidence and encourages conversion. The documentation is presented in a very beautiful way, and is logically arranged. This results in a great – borderline fun, in fact – experience.

Conclusion

In the rush to provide more complex, interesting, and useful systems, we often forget that developer experience is a huge part of this. Being able to provide extensive, well-formed documentation is vitally important. More than this, being able to provide said documentation in a unique format that adds value to the developer experience is even more so.

While you don’t necessarily have to do everything that’s been noted in this piece, taking even a small cue from these examples can lead to a better product, a better experience, and an overall better end result.

What do you think makes a good developer experience? Are there any APIs that shine as a golden example? Let us know in the comments below!