Micro Focus is now part of OpenText. Learn more >

You are here

You are here

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

public://pictures/billd.jpg
Bill Doerrfeld Consultant, Doerrfeld.io
Large bookshelf
 

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 books

Read these books and deep dives for the most comprehensive development know-how on REST APIs.
 

A Practical Approach to API Design

A short yet on-point book on holistic API best practices, written by James Higginbotham and Keith Casey Jones.
 

RESTful Web APIs

RESTful Web APIs: Services for a Changing World is published by O’Reilly. Develop a simple API and understand resources and representations, hypermedia, domain-specific designs, and more.
 

REST Design Rulebook

This O’Reilly publication emphasizes how to design URIs and proper HTTP method usage.
 

Architectural Styles and the Design of Network-based Software Architectures

Take a look at the momentous work that inspired it all. Discover REST constraints by reading Roy Fielding’s original dissertation, wherein he introduces REST (see Chapter 5).
 

Little Manual of API Design

Includes great ideas on usability characteristics, how to make readable code, and how to have a best-practice, design-first approach to web API development.
 

CORS in Action

Describes cross-origin resource sharing (CORS) from the client and server perspective.

API design knowledge centers

Visit these free community-maintained resources for quick tutorials, style guide comparisons, and REST API cheat sheets.
 

API Style Book

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.
 

REST API Tutorial

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.
 

REST Cheat Sheets

Whether you’re building microservices, platforms, or strictly APIs, these GitHub repositories offer very quick, straightforward strategy and design guidelines.
 

RESTfulAPI.net

Free helpful guides on things such as caching, content negotiation, idempotence, HATEOAS, and much more. See the related REST API Design Tutorial for specific implementation examples, too.
 

RESTful API Design

From high-level API design to structural data relationships, this blog-style walkthrough offers extensive definitions of REST concepts.
 

RestCookBook.com

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.
 

Awesome API

A curated list of great resources to design and implement RESTful APIs.

API design blogs and digests

Keep up to date with the latest API design trends by following these blogs, digests, and newsletters.


API University by ProgrammableWeb

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.


Nordic APIs

Scandinavian design principles are infused into high-impact blog posts on API strategy, development, design, security, and more. Subscribe for a biweekly digest.


API Design Center

Kin Lane, the API evangelist, tracks and blogs about the API industry. This research project looks at established and emerging best practices around API design.


GET PUT POST

A weekly newsletter featuring interviews with API figureheads.
 

API Developer Weekly

A weekly newsletter featuring bleeding-edge API practices.

API-themed events

Attend meetups and conferences to immerse yourself in API design culture.
 

Web API Events

Check out this page to find out when and where events such as APIstrat, APIdays, API Mixtape, and others are happening. Crucial API design advice is offered at these conferences.

Examples of great APIs

Discover impressive API design by modeling the greats.


Public APIs

A list of hundreds of stunning public APIs, organized by industry.


Google Cloud

Take inspiration from Google Cloud’s internal API design guidelines.


What is your go-to example for a good REST API?

This Hacker News discussion sparked a slew of helpful responses. Developer darlings Stripe, Twilio, Stormpath, Plaid, Last.fm, among others, shine.

Critical industry articles on design best practices

An assortment of design theories from API industry experts. Get to the bottom of error handling, naming, versioning, and other topics.
 

The Ten Essentials for Good API Documentation 

The always-excellent A List Apart magazine tackles the topic of good API documentation with this definitive list of best practices.

UPDATE: Now A List Apart has ten more essential tips in their article Ten Extras for Great API Documentation.
 

Best Practices for Error Handling

Learn how to choose error codes and communicate results with clients. Includes error-handling examples from Box and Facebook.
 

Stripe’s Take on Robust APIs

Solid advice from the Stripe dev team on designing robust and predictable APIs. Overviews idempotency, which eliminates negative side effects from multiple calls to the same resource.
 

Best Practices for Designing a Pragmatic RESTful API

An anti-dogmatic post that gets to practical details quickly and walks through many facets of the API lifecycle.
 

A Massive Guide to Building a RESTful API for Your Mobile App

A large guide (but with TL;DRs) covering best practices for building APIs, web services, and databases for mobile apps and clients.
 

API Names and Begging the Negatives

Helpful reminders on avoiding false negatives in function naming to achieve ultimate readability.
 

Richardson Maturity Model

Martin Fowler breaks down the principle REST approach into three steps: resources, HTTP verbs, and hypermedia controls. A popular way to visualize API elements.
 

RESTful API Versioning Insights

A list of common versioning strategies and alternative versioning approaches that avoid breaking client integrations.
 

The Ultimate Solution to Versioning APIs: Content Negotiation

Another article on how content negotiation can be used as a versioning approach to avoid breaking changes.


API Hierarchy of Needs

API specialist Bruno Pedro reinterprets Maslow’s Hierarchy of Needs to track the creation of self-realized API programs.

Relevant standards

These are the building blocks for the web API space. It doesn't hurt to have them bookmarked.


OpenAPI Specification

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.


RAML

An easy way to design APIs and create a machine-readable definition in the process.


API Blueprint

Another API design format that uses markdown annotations to describe API elements.


JSON

The most popular format for serialized data transfer for RESTful APIs.


OAuth 2.0

The industry-standard protocol for authorization, maintained by IETF.


RAPIS

A specification proposal for designing language and format-agnostic APIs.


Significant Hypermedia Styles

HAL, Siren, Collection+JSON, and JSON-LD are all possible frameworks for implementing hypermedia into a REST API.

Add your own resources to this list

Do you have any additional resources on building RESTful APIs? Share them in the comments below, and we will consider adding them to our evolving guide.

 

Keep learning

Read more articles about: App Dev & TestingApp Dev