Designing Web APIs

Chapter 9. Developer Resources

Building a great API is not enough if no one knows how to use it. As you design your API, make sure that you guide and enable developers by providing the learning materials they need to succeed.

Developer resources are a set of assets that you should provide your developers so that they can improve how they use your API. There are many types of developer resources out there, each affecting different aspects of the development life cycle. In this chapter, we cover the major resources that most companies provide. We also provide some tips and tricks to make them work for you.

API Documentation

Let’s begin with the most basic resource that is required for every API or platform—documentation.

Documentation is where developers come to learn about your API. Whether you’re providing a simple README file or developing a full website for your developers, it is critical to clearly document how they can most effectively use your API. There are several different aspects to good documentation, covering all stages of the development life cycle.

Getting Started

Getting Started guides are a common type of tutorial that walk the developer from unfamiliarity with an API to initial success. In many cases, this comes in the form of completing a “Hello World” exercise—a reference to the common practice within the engineering profession of getting a program or API to churn out “Hello World” as a proof of success. The API doesn’t literally have to return “Hello, world”, ...