Developer Experience is the UX of Your API

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.


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.

More reading:

Swagger => OADF: Insider View

I still don’t get it. After multiple clarifications with a friend about the recent donation of the what-once-was-only-Swagger API description format to the OAI (Open API Initiative), I’m still confused as to why the contribution of the impartial format without what would be very one-sided contributions of tooling around the format is not the safest step to getting a long-term standard for everyone to benefit from into the public domain. I argue, it is, even if we don’t know how it will turn out.

Not at the cool kids table, what do I know?

I get that some people are feeling confusion, frustration, shock, and even disgust. I also hear people expressing relief, clarity, gratefulness, and vision. The world has far fewer thought-leaders and way more people who want standards they can build cool shit with, make some money and some good happen, and ultimately go home knowing things will generally work as designed again tomorrow.

I’m about to state some things, job whatever. I had no say in the way any of this played out, but we need someone to clarify that the insides of my corporate office is filled with good, fair, and driven people. This is not an evil empire, unlike some other soft competitors, this is where I work. Respectfulness and honesty are two of the Apache Way tenants, two that ring true for me and those I work with.

What are the facts IMO?

Fact: Certain entities owned the rights to the Swagger technology and brand, which for better or worse started as a format plus a cool name mingled together. It eventually became so useful that the format was open-sourced. Later, a company was able to navigate the financial and political mess that has been the API description format landscape for years, producing an API ecosystem standard as significant to real implementers as other open standards like HTTP, JPEG, and . Still, the brand has monetary value but the spec has much broader universal value, and so the spec was donated.

Fact: No one could “sell” the Swagger format is because it was already open source, and though the brand was still legal property, it has been managed with no misinformation or clandestine story behind it. When technology becomes part of a commons, it no longer makes sense to have one brand dominate the tooling and the vendor ecosystem. A separation of the format and the brand was necessary. To convolute the new OADF (Open API Description Format) by including tools that specific vendors donated but not including others would have been even worse an idea than not separating out the format from the brand, and persisting to do so doesn’t prevent these tools from being just as useful and successful as they were before the OAI changes.

Fact: People that truly helped the Swagger ecosystem get to where it is today deserve due credit for what they have done. Their contributions continue to be pivotal to the OADF because without a community, big companies that are already strong-arming the media with boku marketing budgets and completely horse shit press releases will take the OAI over and rule the connected world, one bad choice at a time. The community must maintain leadership in the OAI, and if there’s no room at that table for proven thought-leaders who have already spent years improving and evangelizing the importance of a format like Swagger, then shame on those who say they are leaders but are to busy making ends meet to ask for the right kind of help or spearhead truly pivotal contributions to the open web.

Fact: SPDY was a great start to fixing something, and I liken the work done at Google with the help of the whole industry to elevate much of the great ideas there into the formal HTTP 2.0 spec. Same with WebRTC, if only we could get proprietary chipset manufacturers to be adults and ship more than one optimized instruction set for video decoding on their silicon communion wafers. Much like the SPDY-to-HTTP2 evolution, the need for a standard API description format is long overdue, the OADF being a necessary leap forward which should have happened years ago.

What are we left with in the OADF?

I admire people who stand up for what they feel is right and who are vocal about what happens when things don’t go the way they expected them to. A brand is monetarily valuable, search and replace on the internet is not possible (I get that), and decision-makers usually make the decisions they are hired to make. That’s just how that works.

In the meantime, we have a standard open API description format now, frankly better than all the rest of them, and we can build on it just like all the other foundational technology that makes up the connected world we live in today. Brands are bullshit anyway. It’s the meaning of the thing behind the name that matters.

Peace, love, and internet for everyone.