Building RESTful APIs

Design restful APIs through deliberate tradeoffs, exposing core functionality with well-named affordances, and choose bolt-on, greenfield, or facade strategies to balance evolution, compatibility, and versioning.

Model your API effectively by following three rules: choose a useful modeling approach, document everything, and involve developers, support, QA, and docs early to surface assumptions.

Identify participants in API modeling, including people and entities like IoT devices and payment processors, name each participant, and classify internal or external and active or passive.

Identify participants and activities in ordering a book online, mapping customers, stock clerks, and customer support, with steps from finding items and adding to cart to checkout, payment, and shipping.

Identify core resources, treating them as nouns like items, carts, and orders. Group API methods around create, retrieve, and update to form the API definition.

Explore mapping nouns to HTTP verbs in a restful API by modeling items, carts, and orders with get, post, put, and delete, including independent, dependent, and associative relationships.

Validate your API early with cheap, fast methods by mapping use cases and simulating endpoints as if the API exists.

Explore how HTTP underpins REST APIs and why REST is not a standard, specification, or protocol. Understand headers and payloads—HTML, JSON, or XML—as the primary means of communication.

Learn to read common http headers and response codes across 2xx through 5xx, including 200, 201, 204, 301, 302, and understand content type and rate limits for api clients.

Explore the six rest constraints that shape rest APIs—client–server architecture, statelessness, cacheability, idempotence, layering, and recognize these as guidelines for a flexible, scalable design.

Examine code on demand and the uniform interface, detailing how resources are identified by URL, manipulated via representations, self-descriptive messages, and navigated by hypermedia.

Explore authentication versus authorization in API design, compare API keys (URL vs header), warn against rolling your own protocols, and adopt OAuth 2.0 with OpenID Connect.

Choose between content negotiation via the Accept header with media type versioning and explicit versioning in URLs to manage API versions with clarity.

Compare three popular media types for API payloads—collection+json, HAL, and the iron hypermedia type—and learn how to structure data and links for self-descriptive, uniform interfaces.

explores hypermedia as a non-linear, media-rich approach to restful APIs, using a single entry point that returns links for next actions and contextually guided discovery documents.

Learn how HTTP headers enable content negotiation and caching in restful APIs. Discover accept headers that negotiate formats and ETags that reduce payloads for faster, bandwidth-saving requests.

Explore effective documentation approaches for restful APIs, favoring version-controlled, code-snippet friendly, searchable platforms over PDFs, with recommended tools like wikis, static site generators, and Slate.

Evaluate when an SDK truly simplifies users' lives, guided by Spoil principles—succinct, purposeful, open source, idiomatic, and logical—while focusing on common scenarios and community contributions.

Take the next steps by joining local user groups and exploring online resources from Mike Amundsen and the API craft mailing list, including Collection JSON for restful APIs.