Developer Experience (DX)

There are many ways to think about Developer Experience (DX) and what “good” DX looks like. Thinking about DX early and often is particularly important when it comes to designing and constructing APIs, especially open APIs.

In his presentation titled “Developers are People Too! Building a DX-Based API Strategy”, Ronnie Mitra provides a helpful working definition of DX:

The sum of interactions between a developer and the API owner.

To give credit where credit is due, many people now writing about DX reference a 2012 talk by John Musser at the O’Reilly Open Source Convention (OSCON). In particular, people tend to focus on Musser’s 5 Keys to a Great API:

• (V) Valuable
• (P) Planned
• (F) Flexible
• (M) Managed
• (S) Supported

Valuable

Arguably the simplest way to conceptualize of value in the context of an API is developer engagement, and Musser offers excellent advice about what constitutes value:

• Make it clear what the API does
• Provide instant signup
• Provide free access
• Be transparent about pricing
• Provide great documentation

For another way to think about the value of an API, instead of thinking of the business value of the API itself, it is helpful to frame it as “the value of the effect of the API.” That is, an API’s value is closely associated with to the extent to which it enables access to the value that an organization delivers.

The value of any API, therefore, can be seen as the result of an API call — the service request and response — rather than the API call itself.

As noted in this article on Forbes.com:

APIs are a simple way to provide access to some type of business assets. The business asset can be information itself, information about a product or service, or direct access to the product or service.

Broadening the perspective on the value of APIs even further, in a 2015 article in Harvard Business Review, Bala Iyer and Mohan Subramaniam observe that there are two primary value propositions associated with APIs:

• APIs can be engines for rapid growth via third party development and other partnership opportunities. One of the examples of this that the authors cite as evidence is the meteoric growth in the use of Google Maps only after a third-party developer made it possible to show real estate locations on a map.
• APIs can be the enablers for exposure to new markets and ecosystems. One of the most commonly occurring examples of this phenomenon is the range of products and services that fall under the Internet of Things (IoT) umbrella.

In the OSCON 2012 presentation referenced above, Musser identifies five areas with which API value is most often associated, which are potentially valuable separately, and are especially valuable when combined:

• Value of a service
• Value of data
• Value of (exposure to) an audience
• Value of functionality (as an enabler of getting things done)
• Value of (exposure to) a market

Planned

For insight into how much planning has gone into building a developer community around an API, it’s worth looking closely at the Developer Portal (or similar construct) with which it is associated. There are many examples of that are worthy of emulation.

context.io

There are numerous things to like about the context.io product page, such as:

• Being able to get an API key right at the top of the page
• Seeing a carousel of sample implementations right below the link to the API key
• Making available a simple explanation of the value proposition of the API

NPR One Developer Center

Some attributes of the NPR One Developer Center that set it apart from the crowd:

• Simple and visually appealing design
• Clear explanation of what you need to do to get started quickly
• Concise description of what the API does
• Swagger-based API Reference

Note: in the interest of full disclosure, I am an NPR employee, and one of the teams I work with is the one that built, and continues to maintain, the NPR One Developer Center.

Twilio API & Docs

Twilio’s API and associated documentation is particularly rich in a number of areas:

• Prominent placement of the sign-up link
• Tutorials that are broken down by product, platform, and programming language
• A nice collection of helper libraries and SDKs
• Examples of what has been built based on core use cases

Note: For additional advice about what developer-friendly documentation can potentially look like, the team at Trigger.io has put together a post with some helpful advice in this area — Designing Docs for Developers.

Flexible

When it comes to making sure that flexibility is getting due consideration in an API context, this is an area where there tends to be a broad spectrum of opinion. As Steven Wilmott writes, simplicity and flexibility go together. And, he says, how flexible an API is comes down to the answers to two questions:

1. How large is the potential space of (sequences) of operations that would make sense given the data and operations available within the systems / data stores underlying the API? and; 2. What subset of these are possible via the API?

Ultimately, as Wilmott and many others have pointed out, the clearest signal of how well an API achieves simplicity and flexibility comes down to one simple measurement: Time To First Hello World (TTFHW). As Wilmott goes on to say,

Getting people to this goal quickly builds confidence that the API is well organized and things are likely to work as expected. Delaying the “success moment” too long risks the developer going elsewhere or shying away from bigger projects.

Another way to assess API simplicity and flexibility is what some people refer to as Time To First Paid App (TTFPA). To make this term even more general, to include apps that are not intended to directly generate revenue, let’s say Time To First Working App (TTFWA).

Managed

When it comes to management of APIs, arguably the most controversial of topics is API versioning. Rob Zazueta sums it up this way on NARWHL:

Versioning your API is terrifying. If you push out a ‘breaking change’ — basically any change that runs counter to what client developers have planned for, such as renaming or deleting a parameter or changing the format of the response — you run the risk of bringing down many, if not all, of your customers’ systems, leading to angry support calls or — worse — massive churn. For this reason, versioning is the number one concern among the development teams I work with when helping them design their APIs.

Given that opinions on the topic of versioning will continue to differ, one of the best pieces of advice that Rob offers in the post on NARWHL above is to consider adding a link to resource responses that have been up-versioned. The advantage of this is probably obvious — it enables the client developer to decide how to handle such updates from within their code. In Rob’s example, if a developer were to be using an outdated version of the API, they potentially could get an additional link in the response that looks something like this:

"_links": {
    "rel": "urn:deprecated",
    "href": "http://api.example.com/alerts/735432",
    "method": "GET"
}

There are a number of additional steps that can and should be taken, which Rob goes on to describe.

Note: When it comes to management of APIs, there are a great many other things that require consideration. Steve Wilmott provides some helpful advice in this area in his post about API management and infrastructure.

Supported

Even though “Supported” is the last of the five areas to be covered in this post, it is easy to argue that proper API support is the most important of the five areas when it comes to a positive Developer Experience.

When it comes to API support, one of the most important topics worthy of consideration falls under API change management. The type of change management that tends to get the most attention is how to handle “breaking changes.”

As described in an eBook titled The API Owner’s Manual: Best Practices of Successful API Teams, in general terms, introduction of new methods or changes to existing methods tend to be non-breaking changes, while removal of methods or changes to methods that involve removal of data or otherwise change payloads tend to be breaking changes.

The authors of the API Owner’s Manual go on to offer the following advice:

It can be extremely difficult to be certain changes won’t break some apps. For these reasons we strongly recommend that absolutely any changes to the API, even if categorized as ‘non-breaking,’ should be rolled out by: 1) providing a test endpoint with the new version prior to launch and, 2) sending an email or other communication to developers informing them of the change and giving timing/details.

The above examples constitute support during runtime. There is also another type of support that is needed, earlier in the process, during development time.

Not surprisingly, what is most important from a support perspective during development time tends to be very similar to what is most valued in developer portals. Examples of the most helpful support content/tools at this early stage include:

• Overview documentation
• Reference documentation (often generated directly from code)
• Sandbox tools
• Code samples
• Interactive forums