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.
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.
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
