API Stylebook

Deliveroo API Design Styleguide added on the API Stylebook

Sun, 23 Apr 2017 00:00:00 +0000

The Deliveroo API Design guide has been added the API Stylebook! This is a MUST read for any API designer.

Deliveroo is a British online food delivery company. Orders are placed through its website and then either employed or self-employed bicycle, motorcycle or car couriers transport orders from restaurants to customers. Source [wikipedia]https://en.wikipedia.org/wiki/Deliveroo

These guidelines can be sum up with this quote:

We choose to adopt three general principles. Here’s a shortcut to remember:
RESTful, Hypermedia, Fine-grained

They are internal apis oriented but contains some interesting considerations and precisions for external APIs and the duality of internal/external design.

API Documentation is briefly explained with 3 lines but contains 2 powerful quotes that everyone working with API MUST have in mind:

API users are both developers and machines
Discuss APIs before starting any implementation

This document contains a really interesting section about API and domain modelling based on Domain Driven Design. This sections helps reader to model resources and their relations.

Deliveroo engineering teams promote wisely the use of Hypermedia (but please, just stop using this ugly HATEOAS acronym!).

More importantly, consumers should not need to construct URLs, instead using only URLs dynamically discovered in responses.

This is the first analyzed document to deal with internationalization.

Two approaches of versioning are described, one for internal facing APIs and another for external facing APIs.

How deliveroo engineering team handles errors beyond HTTP status is simple and brilliant.

The results are not just intended to be acted on by machines, but rather presented to users.

Caching is explained in depth.

Caching efficiency is a critical aim of well-designed APIs, as it is influential on service performance; cache consistency is as important.

These guidelines are definitely a MUST read for any API designer. If you want to see all topics covered by this document go to the Deliveroo API Design guide on the API Stylebook.

Note: there’s a minor contradiction concerning HTTP status code return by PATCH (both MUST and MUST NOT return 200), an issue has been declared.

Google API Design Guide added on the API Stylebook

Sun, 05 Mar 2017 00:00:00 +0000

Google shared its API Design Guide with the community and it has been added to the API Stylebook.

This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide we follow when designing Cloud APIs and other Google APIs. It is shared here to inform outside developers and to make it easier for us all to work together.

This guide is slightly different from the other ones because it deals with REST and RPC API design focusing on gRPC APIs using Protocol Buffers v3.

This guide applies to both REST APIs and RPC APIs, with specific focus on gRPC APIs. gRPC APIs use Protocol Buffers to define their API surface and API Service Configuration to configure their API services, including HTTP mapping, logging, and monitoring.

People who are not familiar with gRPC and proto3 may be taken aback by this guide, but it’s really worth reading for any API designers or anyone wishing to use Google Cloud Endpoints.

The documentation section is really interesting giving guidelines on how to write your API (technical) documentation. If you remember only one thing concerning documentation, let it be this quote:

In most cases, there’s more to say than just restating the obvious

Versioning and how to determine if a change is a breaking one or not are very well explained (see Versionning).

To have a quick look at all the topics covered by the Google API Design Guide, click here..

The API Stylebook

Sat, 10 Sep 2016 14:13:00 +0000

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