API Academy

Sponsored by Layer7

API Design 102: The Developer Experience

By Ronnie MitraPosted on

One of the key principles of good API design is that an interface must provide a seamless and user-friendly developer experience (DX) if it is to facilitate the creation of applications that add value to the API owner’s business. In this lesson, we explain the importance of a focus on DX and provide an overview of developer-focused API design principals.

Product designers understand that focusing on how their creations will be used in the real world is a key step in building products that consumers will actually want. For example, by taking a user-centric approach, designers of mobile devices and operating systems have massively increased the popularity of their products. This focus on improved usability is also central to good API design. While traditional product designers focus on the user experience, an API designer strives to improve the developer experience (DX). Developers must be able to easily leverage the functionality an API exposes if that API is going to enable the creation of truly valuable new Web and mobile apps. Shifting the focus of design from technical aspects of the backend systems an API exposes to the manner in which that API will be consumed by developers can greatly improve the experience of using it. Ultimately, improving an API’s usability will result in higher adoption rates and lower integration costs – both of which are important goals for any API program. There are many strategies and solutions that can be used to make these improvements. A good general rule of thumb is that API designers should try to create their interfaces from the perspective of their target developers. More specifically, there are a number of key goals that an API designer hoping to create an excellent DX must be aware of:

  • Facilitating troubleshooting (e.g. providing useful error messages)
  • Simplifying change management (e.g. implementing an API versioning strategy)
  • Improving visibility (e.g. providing log and usage access)
  • Establishing trust (e.g. communicating a sense of stability and longevity)

Perhaps the most important area of focus for DX-friendly API design is minimizing the learning curve, making it simple for developers to create powerful applications, fast. There is a great deal that API design can do here but – to be truly effective – these efforts must be integrated into a broader scheme for educating developers and growing a self-supporting dev community.

Providing comprehensive, easy-to-use documentation is vital to minimizing the learning curve. Also, engaging directly with the developer community (e.g. via online forums) can be a highly effective educational strategy. This kind of direct engagement also helps to increase adoption and minimize guesswork involved in attempting to meets developers’ specific usability needs. To conclude, it should be clear that – alongside key business goals – the needs of developers represent a fundamental driver of good API design decisions. Broad decisions will be driven by the specific nature of the developer audience (e.g. is it internal or external?) while more granular decisions will be driven by the need to provide an excellent DX.