Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News What is API Developer Experience and Why It Matters

What is API Developer Experience and Why It Matters

This item in japanese


API developer experience is a relatively novel focus aimed to improve API design so it provides a seamless experience to developers when writing software. It can help increase programmers’ efficience and make it easier for developers to achieve goals on behalf of end users.

Jeremiah Lee Cohick, software engineer at Fitbit with a penchant for user experience, frames API experience in the broader developer experience (DX) field. DX encompasses many aspects of the relationship between programmers and the platform they are developing for, such as trust, education, tools, and platform usability. Specifically, he describes API experience as the UX of APIs, which ends up being a critical part of the development cycle phase dedicated to writing code. In a 2014 presentation at Web Directions, Cohick identified four key concerns that can help reach the goal of API excellence:

  • Functionality: what problem the API solves and how good it is at that. An API should not only strive for effectively solving a problem, it should also solve it very well.
  • Reliability: a set of non-functional requirements such as availability, scalability, stability, etc. that can help build trust and represent a necessary ingredient in driving developers to use an API.
  • Usability: how well does an API lend itself to discover and learn how its functionality can be used (intuitability)? How easily does it allow developers to create tests? What support does it provide for error handling?
  • Pleasure: how enjoyable is an API to use?

According to Cohick, when all those pieces fit well together they provide a great developer experience and their absence or imperfection are usually the source of pain and confusion.

Amit Jotwani, Sr. Developer Evangelist & Product Lead at Intel Mashery, says that “people who are really serious about API should care about developer experience”. He suggests ten steps towards great API experience, which :

  • Keep it simple.
  • Avoid marketing jargon and be clear about what developers can stop doing if they use your API.
  • Simple and fast signup, which also includes easy management of API keys, service selection, etc.
  • Fast setup time: ideally, only 5 minutes should be required to create an “Hello World” app.
  • Fast API key provisioning to spare developers long waits.
  • Clarity about costs and limitations; do not create excessive expectations; provide free trial.
  • Provide stellar documentation that is complete and up to date, and avoid using PDFs.
  • Provide interactive documentation, such as the Mashery API explorer and Klout interactive console to make it easier to discover and learn APIs.
  • Show the code, poroviding clear and concise examples of the way an API can be used for a given task.
  • Inspire developers and be available on channels such as Stack Overflow, Twitter, etc.

According to Ronnie Mitra, director of API design at the API Academy, a consulting company helping organizations to improve their APIs, API experience starts from the recognition that developers are people too. The API designer, says Mitra, should set four key goals in order to create an excellent DX:

  • Facilitating troubleshooting (e.g. providing useful error messages)
  • Simplifying change management (e.g. implementing an API versioning strategy)
  • Improving visibility (e.g. providing log and usage access)
  • Establishing trust (e.g. communicating a sense of stability and longevity)

In a talk at the Nordic APIs conference in Stockholm, Mitra proposed a frame similar to Cohick’s to help design great APIs and that has three main pillars: functionality, usability, experience. In this context, usability shifts the focus from the functionality/reliability level towards developers, aiming at making APIs easy to use. Experience concerns itself with how the developer feels about all of the interactions with an API and its providers, and builds on top of both functionality and usability.

According to Mitra, the key to providing a great API experience is to understand its audience. This can be done by defining personas representing typical API consumers.

You can’t design for usability if you don’t know who is using your API

Once personas are defined, usability aspects of an API can be evaluated along several dimensions, based on the work of Steven Clarke at Microsoft:

  • Invocation Ratio: How many calls does it take for the developer to accomplish their desired task?

  • Structure: How deep is the required data located? What is the signal to noise ratio?

  • Navigation: How difficult is it to move from one result to another? How difficult is it to locate a required datum?

  • Developer Stack Size: How many new components are needed?

  • Time to First Call: How quickly can a new user make their first API call?

  • Errors: How difficult are they to fix? What is the nature of the error? (unpredicted result, invalid input, out of sequence, etc…)

Similarly, the experience an API provides have the following aspects: engagement, pleasure, familiarity, trust, and safety, that can be used to guide the design process. Those aspects are a direct product of an API’s usability qualities.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • In client - server do not forget client

    by Erik Gollot,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Agree with everything. I could add that we should add 'client' call samples when you provide a server api. A sample that shows all bootstrap code that you sometimes need before you can 'reach' the final call to the provided API.

  • UX, DX, XX

    by Jeff Hain,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    The title looks like a reference to "How To Design A Good API and Why it Matters" by Joshua Bloch, but Josh was just proposing rules for development, not trying to create a new field.

    I wonder if siloing away different aspects of the work into fields of their own is a good tendency. For example, sometimes you need to do tradeoffs between developer experience and performances, etc.

  • Re: UX, DX, XX

    by Florian Sommer,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Indeed usability as a quality attribute is an architectural driver and thus can conflict with or support other qualities like performance, security etc. ... That's one more reason to spread the news that UX matters to all the different roles involved in software engineering, including developers.
    And I think that's the goal of the article(?) I mean, actually I can't read anything about "siloing" the ux aspect away in the article. I took it more like "hey, dev xp matters, be aware".

  • Re: UX, DX, XX

    by Jeff Hain,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    >"I can't read anything about "siloing" the ux aspect away in the article"

    By siloing away I was just refering to the fact of regrouping these considerations under a name (DX), and soon having "DX experts" inadvertently causing new tradeoffs-unaware organizational fads etc. (I seem to always see the worst coming, but eventually it does ;)

    I think that being cautious about conceptual inflation, overlabeling things and putting them in these little boxes that names are, casting shadow on them, helps to keep a holistic view and not miss out on the subtleties of their relationships with other aspects of reality.
    Especially because reality can be mentaly divided into many different ways, creating inconsistencies that actually don't exist, for they are just conventional, and cause more issues than they solve.

    Recently there was a presentation by John Housego
    he said (at 7m50s):
    "We don't want associates to be poured into a box, and giving them a title gives them a box."

    Similarly, if you give you skills names, you pour them into boxes.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p