API patterns

This section covers some familiar design problems while working with APIs.

Pattern – human browsable interface

Problem: Visiting an API in a browser is a jarring experience, leading to poor adoption.

Solution: Use the opportunity to provide a human browsable interface to your API.

Problem details

Even though APIs are designed to be consumed by code, the initial interaction is typically by a human. A working implementation might respond with correct results if the right parameters are passed, but without proper documentation, it can be unusable.

Under-documented APIs can reduce collaboration by different teams with your application. Often, required resources such as conceptual overviews and getting started guides are not found, leading to a frustrating developer experience.

Finally, since most web APIs are initially accessed using web browsers, an ability to interact with the API within the documentation itself is very useful. Even if the documented behavior differs from the code, the...