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
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
