A guide to RESTful API design: 35+ must-reads

When it comes to designing web APIs, no other style is more respected than REST. Outlined by Roy Fielding in his famous dissertation, REST, or representational state transfer, has become the go-to method for designing powerful APIs that run over HTTP.

Resource naming, hypermedia, proper HTTP method usage, caching, idempotence, versioning, and other API design elements all come with best practices. For API developers, learning the nuances of RESTful API design is critical if they want a high adoption rate for their APIs.

However, a lot has been said on the topic, so I’ve assembled this collection of more than 35 top resources on REST API design—eBooks, tutorials, and articles—that will not only get you up to speed, but act as a guide throughout your API development lifecycle as well.

API design knowledge centers

An awesome project by API Handyman that collects many API design guidelines from big-name companies and lets you compare individual topics side by side. For example, see how Atlassian, Cloud Foundry, PayPal, Red Hat, and many others implement hypermedia.

What is REST? This mini-tutorial by Todd Fredrich on REST API design explains the six constraints of REST and has excellent quick design tips, a status code cheat sheet, and other helpful open-source tools.

How to do things RESTful. What are idempotent and/or safe methods? When do you send 4xx or 5xx codes? What is the Richardson Maturity Model? This API design knowledge center answers many common questions you may have.

API design blogs and digests

Cataloging over 17,000 web APIs, ProgrammableWeb hosts the largest directory of APIs and SDKs. In addition, it provides news updates and features the top articles in the API University, which accumulates best practices on API-first design principles.

Relevant standards

The industry-standard API definition language. Used for describing APIs, documenting APIs, and more. It is overseen by the OpenAPI Initiative, a Linux Foundation group whose members include Google, IBM, Mashape, Smartbear, and many others.