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 short yet on-point book on holistic API best practices, written by James Higginbotham and Keith Casey Jones.



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.



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



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.



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.



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.



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



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.



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



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.



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.

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.

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

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.

A weekly newsletter featuring interviews with API figureheads.



A weekly newsletter featuring bleeding-edge API practices.

API-themed events

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



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.

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

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

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 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.



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



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.



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



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



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



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



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



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

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.

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.

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

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

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

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

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