The API Stylebook

Designing and providing APIs, even a single one, is not an easy task. Beyond purely functionnal matters, e.g. what does an API, there are many other non functionnal requirements to take care of: What is a resource? What is a collection? How to name them? How to handle errors? How to deal with pagination? How to handle asynchronous operations? Which case use to name properties? How to handle versioning? How to …

To ensure consistency, to ensure maintainability, and above all to ensure good developer experience, these questions must be answered and these answers must be applied consistently.

All these questions may not come to mind from the outset. They may even come to mind far too late. All these questions may not be answered easily. Some will reinvent a square wheel, some will lose themselves searching answers for days.

But some people already have been through this, some people already have shared all this. What we need is to find this information easily.

The API Stylebook aims to help API Designers to solve API design matters and build their API design guidelines by providing quick and easy access to selected and categorized resources.

The API Stylebook name has been inspired by the AP Stylebook which is a writing style guide for journalists published by the Associated Press.

In this first version the API Stylebook provides direct links to specific topics within publicly available API Design Guidelines. Instead of reinventing the wheel or searching google for hours, API Designers quickly can find solutions and inspiration from these existing guidelines.

Stay tuned for updates, follow the API Stylebook on Twitter