In the 2019 State of API report, surprisingly, only 37% of API providers viewed documentation as a top priority. When API consumers were asked to vote on the most important characteristic of an API, 60% earmarked “ease-of-use” as their primary desire when integrating, with documentation trailing in 3rd place. While documentation can contribute to overall ease of use, these numbers reveal that it is not the only element that plays into a good developer experience.

So, the question is: How can API companies improve their overall process and deliver the high-quality experience their users want? One of the best answers to that question is: Focus on creating a dedicated developer experience team that can empower your users by making it easier to understand, easier to build, and easier to integrate (particularly if your company develops customer-facing APIs).

Understanding the Difference: DevRel and DX

What exactly is Developer Experience (DX)? DX is all about understanding developers, their needs, their abilities, their values, what they’re trying to accomplish, what tools and technologies they’re using, the integration points, and how they feel while using a product.

Developer relations (DevRel) is a vital component of a comprehensive DX strategy. Some companies are large enough to have a dedicated DevRel team, perhaps even with multiple distinct roles, including evangelists, advocates, and sometimes even tech writers and growth hackers. These roles are all aimed at inspiring positive relationships with developer users, through sharing knowledge that fills the gap between the creators and consumers of tech.

Whether your company has a dedicated DevRel team or a DX team that includes DevRel responsibilities, it would be remiss not to acknowledge the role developer relations plays under the larger umbrella of developer experience.

Why Developer Experience?

Software companies and SaaS providers that sell user interface (UI) products have recognized the importance of good user experience (UX) for decades. A great UX can be the key differentiator that makes your product successful. It’s how Apple won the cell phone market and how Nest made thermostats sexy.

DX is to APIs as UX is to UIs. APIs are products, and developers use those products. Those developers have come to expect a high level of quality, ease-of-use, onboarding, and support thanks to companies like Stripe, Nexmo, and HelloSign, who are continually raising the bar.

“DX is the acquisition of knowledge needed to implement an API. Make the acquisition easier; knowledge more digestible; the journey of implementing it simpler; lives of developers better” — Anthony Tran, creator of the Luna design system

Why the Shift?

So why are companies suddenly starting to realize that they need a DX team? After all, they’ve scraped by without DX for decades. What changed?

In the early 90s and into the 21st century, businesses typically invested millions of dollars in on-premise software packages such as CRMs, ERPs, and databases. They then relied on an army of expensive contractors to customize these products to meet their needs. Integrating in decades past was a big undertaking — in terms of skill, labor, and capital.

However, as companies have moved into the cloud, they’ve shifted away from monolithic software platforms and toward smaller, micropayment-based SaaS products. This propagation of SaaS products has led to the need for standardized integrations between them, which in turn has fueled the rise of the API economy. By 2011, REST was an industry standard, and in just under a decade, we’ve seen nearly a 1,000% increase in the number of APIs on the market.

This Cambrian explosion has virtually eliminated the need for expensive consultants who understand the intricacies of million-dollar software packages. It’s now possible for any developer to integrate with these APIs to link disparate systems and automate their companies’ workflows.

The API economy has created a culture of expectation for APIs. It’s now assumed that an API will be readily available, and in many cases unmetered, for consumers or developers looking to “connect” to your application. In fact, for many customers, your API is more important than your UI. Whether you have an API and how easy that API is to use may be the differentiators that make the customer choose your product over your competitor’s.

So, how do you ensure they get the best, most well-rounded API?

You Need a Dedicated Developer Experience Team

Developers aren’t the best at incorporating UI into their designs. That’s why many companies employ UI specialists who are responsible for putting in a friendly interface on top of the components a dev team has built.

The same holds for APIs. Your dev team shouldn’t be solely responsible for an API’s developer experience, because that’s not the dev team’s specialty.

During ShipEngine’s early days, one of the defining moments for our development team was recognizing that to increase adoption we had to provide more focus on creating a product that developers loved enough to justify building out a new integration. We weren’t the first shipping API on the market, and we won’t be the last, so we knew we needed a way to stand out.

We started to look at how API companies in other industries navigated around their competition.

Take popular payment processing platforms like PayPal and Stripe, for example. Many may recognize PayPal as one of the leaders in the industry — and, as one of the first on the market, they deserve a seat at the table. But, historically, their API has been clunky and awkward to use. When Stripe was first introduced, they knew they were offering a product that developers would love, but also knew gaining a loyal following would require a lot of legwork.

How were they able to do it?

By building an API with a good DX. 

They designed a killer API with an emphasis on consistency and quality standards, wrote user-friendly documentation, provided useful code samples and powerful SDK libraries, wireframed their website to prioritize developers’ needs, and they employed a great developer relations team that attended conferences and wrote knowledge-based articles. They hacked their way into a tight market by creating a product that developers loved, and experience they would want to share with others.

“Happy developers are chatty developers, and when we talk to each other to recommend products, the ones with the best DX are at the top of the list.” — Sam Jarman, DX speaker and writer

Stripe capitalized on their ease-of-use, knowing they could lean on developers to sell their product for them so long as they could show them how pleasant the integration experience could be. Their success was even enough to make PayPal jealous.

So, what’s the takeaway?

Stripe is not the only company to quickly take over market share through improved developer experience. So how were they able to corner the market in such a short amount of time? I believe it was by employing a diverse multi-disciplinary team dedicated to the four primary elements of developer experience.

4 Main Responsibilities of a Developer Experience Team

At ShipEngine, our Developer Experience team exists to ensure an exceptional experience for the developers and customers using our API products. By focusing on these four primary areas of responsibility, we’ve been able to design better features, champion the interests of developers, translate feedback, and advise other internal departments on how to better empathize with and design for developers.

The four primary areas are:

1. API Design

While product development is largely left up to engineers and product teams, a Developer Experience team should maintain responsibility for providing the guidance and standards engineers need to create a product that is received well by others. This includes every part of its interface, including the protocol, style, naming, models, operations, authentication, status codes, headers, errors, paging, sorting, querying, and more. It may also include some aspects of the behavior and implementation details of the API as well. Types of Deliverables:

  • Design guidance
  • Design review
  • Style guides
  • Specifications / definitions

2. Quality Assurance

With APIs, you always want to aim for quality through consistency! To ensure an API product and developer tooling meet a high standard of quality, the DX team must become responsible for employing automated tests, linters, and processes that verify compliance with designs, schemas, and style guides. Quality assurance also involves the propagation of a culture of quality throughout the design, product, and engineering teams. Types of Deliverables:

  • Contract testing
  • Specification testing
  • Style guide compliance testing
  • Verifying accuracy and clarity of docs and tooling

3. Developer Tooling

You want to give developers a chance to test out your API before investing in full integration. So, providing a robust library of developer tools is a great way to show not tell them how great you are. Developers want and need schemas, code samples, reference implementations, SDKs, and a variety of other resources to help guide them through the build-out. Types of Deliverables:

  • Code samples
  • Demos / reference implementations
  • SDKs and libraries
  • Specifications, definitions, and schemas
  • Internal tooling and automation
  • Integrations with developer tools and services

4. Developer Relations

And finally, the role we (and users) are most familiar with. All communications and interactions with developer customers, such as documentation, training, release notes, community events, and user feedback studies fall underneath Developer Relations. Deliverables:

  • Documentation / Tutorials / FAQs
  • Release notes / changelogs
  • System status info (downtime, bugs, performance)
  • Media content (blogs, videos, etc.)
  • Training and materials
  • User research studies
  • Events/community engagement (meetups, hackathons, conferences, etc.)

Final Thoughts

Just as UI/UX has been a key differentiator for Graphical User Interface products, Developer Experience is a key differentiator for API products. And, a good DX strategy extends beyond the roles and responsibilities of DevRel.

James Messinger

About James Messinger

I’m the Developer Experience Director at ShipEngine, where I’m responsible for building an exceptional experience for our growing audience of developers. I’ve spent over 20 years building APIs and developer tooling for companies like Postman, Microsoft, and Dell. I also maintain several open-source projects for OpenAPI, JSON Schema, and Node.js.