4 minute read

For software developers, APIs are a really logical choice for delivering how something should work on multiple platforms, acting as a sort of a common "language" between projects, systems, and teams.

Who really 'uses' an API?

Developers are the real 'users' of APIs. Sure everyone is the downstream recipient of the value of an API, but most of that doesn't happen unless an API satisfies its first audience: developers. They need to understand how it works, how to incorporate it into what they're designing, often designing APIs themselves. When something's hard to understand on an API, they're the ones that feel the pain, not the end user of the app.

You might stretch the definition of an API 'user' to encompass 'anyone who benefits from the API', but it's really the developers who are adopting the API, proliferating it to others, and ultimately orchestrating the user's interaction with your API, like digital gatekeepers. Benefactors and users are important to differentiate between as a business; one represents the volume of your business, the other represents your adoption curve.

Developers love something that just makes sense to them, and a well-designed API along with great documentation the best 'UI' an API can have.

dx-over-ux-equals-api

But APIs don't have a UI!

APIs lacks a User Interface (UI) in the traditional sense, that is until you go back to your definition of who you mean by 'user' when you say 'User Interface'. If the 'user' is a developer that interacts with code and APIs as their primary language, then you leave the UI up to them, but there is still an 'interface' to your API as a product.

Traditional 'UI' focuses on treating the 'user' component in terms of human sensory input and direct manipulation. APIs being purely digital products, they are primarily something you interact with conceptually and socially.

The social element of APIs is huge. By definition, by building an API, you are describing functionality in terms of what 'your' system can do for something else. APIs infer interaction, collaboration, and inclusion.

The role of UI and APIs in the User Experience

User interface (UI) is heavy work in terms of software; people slave over the perfect font, color scheme, and behavioral appropriateness of UI, only to find that the project is hard to maintain, change, or integrate with afterwards. Instead of thinking about how things look, good designers also consider how things behave.

User Experience (UX) design is a field that accommodates these considerations while also maintaining a keen eye on the consumer's actual use, psychological reasoning, and emotional reactions to how a technology works. Yes, we need awesome UI, but only as a result of thinking about the human experience driving the functionality of the software, and only after we get the technical premises correct for the business requirements.

What Makes for a Great Developer Experience?

Developer Experience (DX) is the UX of APIs, but what lessons in great UI design can we apply to DX? What elements of great DX are unique to this non-traditional view of UX/DX?

If I had to boil it down, a minimum-viable API developer experience in order of importance consists of:

  • Documentation, both human-readable and machine-readable
    Hand-crafted API documentation is adorable, but most developers expect an M2M format like Swagger these days. A wise man once said: "he who hand-codes what he could have generated automatically using M2M descriptor is not spending that time making his API better".
  • Minimize number of exceptions, not the exceptions themselves
    I get it. You're special. We're all special like snowflakes. Yay for us. Sad for users of your API. You may have some CRUD operational endpoints on your API, but more than likely you have domain-specific activities that require some explanation. Explain when you deviate from the most obvious, and try to keep things as simple as possible. Be sure to call out any exceptions to your own (internal consistency) rules like naming and type/structure differences between operations. And for the love of whatever, document why you decided to do so.
  • Test the new developer on-boarding process, constantly
    Proving that your DX is what you need it to be must be done regularly. Use hackathons, free account sign-up, metrics, and feedback to make sure that there are no broken elements of the on-boarding chain. If pricing is untenable, you might want to have the business owners focus on that for a bit instead of quarreling over design or feature specifics. Like a reliable disaster-recovery plan, a great DX only comes from putting your expectations through their paces.
  • Be personable, real, and transparent as possible
    Developers are people. Against the perception from non-technical people, they aren't antisocial, they just hate bullshit and like to be passionate about really technical stuff. If your documentation, website copy, and support process reflect genuine concern for helping them solve their problem (and of course you do that too), you'll be our their friend for life, or at least until you have a major outage.

Who Else Says Developer Experience is Essential to A Great API?

If you ask Jesse Noller, you'll get an earful about documentation and transparency, and I agree. Documentation is the first thing a developer will reach for when working with your API. That doesn't mean your efforts in DX should end there. You should also consider how other aspects like performance, authorization, and pricing play in to a developer's decision to implement and evangelize use of your API over another throughout their team and career.

[embed]https://www.youtube.com/watch?v=-vZ_E1OO_PY[/embed]

More reading:

You may also enjoy