How to Create a Great Developer Experience for Your API

What are major differences between similar looking APIs? One of the key differences between APIs is the API developer experience. The competition between API providers is fierce. Due to vast supply of APIs choosing one is tough.

Marc Andreessen said in 2011 that software eats the world. ProgrammableWeb has identified over 22,000 APIs in its API directory. Today it’s APIs that eat the world.

What is a developer experience

Great developer experience can save time and money during the initial API integration. Savings can be even larger during the production use. Great developer experience includes:

  • Relevant content about the API for target groups, and not only for developers
  • Easy to understand APIs
  • Integration flows
  • Examples
  • Prices clearly stated (if applicable)

Developer site is also a marketing website

Developer site is often seen as distribution site for technical API documentation. In fact, developer site should be much much more.

Target audience of the developer site

The content should speak for each target group. The audience is wider than developers, and includes even business users:

  • Business: CEO, especially for startups and small businesses
  • IT: Digital officer, CDO and CIO
  • Technical: CTO, IT architects, including integration and security architects
  • R&D and development: Developers, testers

The content is the king. Yet visual style should not be neglected either in developer site. Visual style should be according to company brand guidelines.

Developer experience as competitive advantage

Easy to use API and clearly stated benefits improve the developer experience. A good developer experience can be even a competitive advantage. 

Well-designed developer site will reflect the benefits of the API. Technically excellent API deserves the bringing up the highlights.

Elements of good developer experience

Stripe is one of the frontrunners in the API world. Stripe developer site contains several elements which make a good developer experience.

Key elements of the developer site – Stripe as the example

The developer site must include at the least the following topics for developers: 

  • Glossary to explain terms. A glossary helps also developers not too familiar with the domain.
  • Getting started guide to outline the integration steps.
  • Examples in the most common programming languages. The “foo” and “test” will not count as understandable content.
  • API reference which outlines the endpoints, expected request and responses and error codes.
  • Release notes helps API users to understand when and how to upgrade the API to a newer version.
  • Limitations to API including request quotas and frequency limitations.

Sandbox allows a quick way to test the API without actual integration. This can be be a major advantage especially in the API selection phase. 

Having easy access to uptime status will reduce calls to customer support. Uptime status page for Stripe includes even Twitter updates about status changes.

As the API community grows, a blog, community pages and forums can be an interactive way to engage the API users.

Steps to a good developer experience

If you are planning a developer site, here are steps to get started:

  • Identify target audience (not only developers, but also business and IT)
  • Design descriptive examples
  • Produce the API documentation and review the contents 
  • Publish the API reference to developer site.

These guidelines are meant not only for public websites, but also for internal developer sites. Begin now the journey towards better developer experience.

Knowing is not enough; we must apply. Willing is not enough; we must do.

Johann Wolfgang von Goethe


You may also like ...

Aavista News

Sign up for monthly news on data and architecture.