RESTful Web APIs: Services for a Changing World

by Leonard Richardson, Mike Amundsen, Sam Ruby

Overview

The popularity of REST in recent years has led to tremendous growth in almost-RESTful APIs that don’t include many of the architecture’s benefits. With this practical guide, you’ll learn what it takes to design usable REST APIs that evolve over time. By focusing on solutions that cross a variety of domains, this book shows you how to create powerful and secure applications, using the tools designed for the world’s most successful distributed computing system: the World Wide Web.

You’ll explore the concepts behind REST, learn different strategies for creating hypermedia-based APIs, and then put everything together with a step-by-step guide to designing a RESTful Web API.

• Examine API design strategies, including the collection pattern and pure hypermedia
• Understand how hypermedia ties representations together into a coherent API
• Discover how XMDP and ALPS profile formats can help you meet the Web API "semantic challenge"
• Learn close to two-dozen standardized hypermedia data formats
• Apply best practices for using HTTP in API implementations
• Create Web APIs with the JSON-LD standard and other the Linked Data approaches
• Understand the CoAP protocol for using REST in embedded systems

Product Details

ISBN-13:	9781449359737
Publisher:	O'Reilly Media, Incorporated
Publication date:	09/12/2013
Sold by:	Barnes & Noble
Format:	eBook
Pages:	406
File size:	4 MB

About the Author

Leonard Richardson (http://www.crummy.com/) is the author of the Ruby Cookbook (O'Reilly) and of several open source libraries, including Beautiful Soup. A California native, he currently lives in New York.

An internationally known author and lecturer, Mike Amundsen travels throughout the United States and Europe consulting and speaking on a wide range of topics including distributed network architecture, Web application development, Cloud computing, and other subjects. His recent work focuses on the role hypermedia plays in creating and maintaining applications that can successfully evolve over time. He has more than a dozen books to his credit and recently contributed to the book "RESTful Web Services Cookbook" (by Subbu Allamaraju). When he is not working, Mike enjoys spending time with his family in Kentucky, USA.

Sam Ruby is a prominent software developer who is a co-chair of the W3C HTML Working Group and has made significant contributions to many of the Apache Software Foundation's open source software projects. He is a Senior Technical Staff Member in the Emerging Technologies Group of IBM.

Table of Contents

Praise for RESTful Web APIs;
Dedication;
Foreword;
Introduction;
Duplication of Effort;
Hypermedia Is Hard;
What’s in This Book?;
What’s Not in This Book;
Administrative Notes;
Understanding Standards;
Conventions Used in This Book;
Using Code Examples;
Safari® Books Online;
How to Contact Us;
Acknowledgements;
Chapter 1: Surfing the Web;
1.1 Episode 1: The Billboard;
1.2 Episode 2: The Home Page;
1.3 Episode 3: The Link;
1.4 Episode 4: The Form and the Redirect;
1.5 Application State;
1.6 Resource State;
1.7 Connectedness;
1.8 The Web Is Something Special;
1.9 Web APIs Lag Behind the Web;
1.10 The Semantic Challenge;
Chapter 2: A Simple API;
2.1 HTTP GET: Your Safe Bet;
2.2 How to Read an HTTP Response;
2.3 JSON;
2.4 Collection+JSON;
2.5 Writing to an API;
2.6 HTTP POST: How Resources Are Born;
2.7 Liberated by Constraints;
2.8 Application Semantics Create the Semantic Gap;
Chapter 3: Resources and Representations;
3.1 A Resource Can Be Anything;
3.2 A Representation Describes Resource State;
3.3 Representations Are Transferred Back and Forth;
3.4 Resources with Many Representations;
3.5 The Protocol Semantics of HTTP;
3.6 Which Methods Should You Use?;
Chapter 4: Hypermedia;
4.1 HTML as a Hypermedia Format;
4.2 URI Templates;
4.3 URI Versus URL;
4.4 The Link Header;
4.5 What Hypermedia Is For;
4.6 Beware of Fake Hypermedia!;
4.7 The Semantic Challenge: How Are We Doing?;
Chapter 5: Domain-Specific Designs;
5.1 Maze+XML: A Domain-Specific Design;
5.2 How Maze+XML Works;
5.3 The Collection of Mazes;
5.4 Is Maze+XML an API?;
5.5 Client #1: The Game;
5.6 A Maze+XML Server;
5.7 Client #2: The Mapmaker;
5.8 Client #3: The Boaster;
5.9 Clients Do the Job They Want to Do;
5.10 Extending a Standard;
5.11 The Mapmaker’s Flaw;
5.12 Maze as Metaphor;
5.13 Meeting the Semantic Challenge;
5.14 Where Are the Domain-Specific Designs?;
5.15 If You Can’t Find a Domain-Specific Design, Don’t Make One;
5.16 Kinds of API Clients;
Chapter 6: The Collection Pattern;
6.1 What’s a Collection?;
6.2 Collection+JSON;
6.3 How a (Generic) Collection Works;
6.4 The Atom Publishing Protocol (AtomPub);
6.5 The Semantic Challenge: How Are We Doing?;
Chapter 7: Pure-Hypermedia Designs;
7.1 Why HTML?;
7.2 HTML’s Capabilities;
7.3 Microformats;
7.4 The hMaze Microformat;
7.5 Microdata;
7.6 Changing Resource State;
7.7 The Alternative to Hypermedia Is Media;
7.8 HTML’s Limits;
7.9 The Hypertext Application Language;
7.10 Siren;
7.11 The Semantic Challenge: How Are We Doing?;
Chapter 8: Profiles;
8.1 How Does A Client Find the Documentation?;
8.2 What’s a Profile?;
8.3 Linking to a Profile;
8.4 Profiles Describe Protocol Semantics;
8.5 Profiles Describe Application Semantics;
8.6 XMDP: The First Machine-Readable Profile Format;
8.7 ALPS;
8.8 JSON-LD;
8.9 Embedded Documentation;
8.10 In Summary;
Chapter 9: The Design Procedure;
9.1 Two-Step Design Procedure;
9.2 Seven-Step Design Procedure;
9.3 Example: You Type It, We Post It;
9.4 Some Design Advice;
9.5 Adding Hypermedia to an Existing API;
9.6 Alice’s Second Adventure;
Chapter 10: The Hypermedia Zoo;
10.1 Domain-Specific Formats;
10.2 Collection Pattern Formats;
10.3 Pure Hypermedia Formats;
10.4 GeoJSON: A Troubled Type;
10.5 The Semantic Zoo;
Chapter 11: HTTP for APIs;
11.1 The New HTTP/1.1 Specification;
11.2 Response Codes;
11.3 Headers;
11.4 Choosing Between Representations;
11.5 HTTP Performance;
11.6 Avoiding the Lost Update Problem;
11.7 Authentication;
11.8 Extensions to HTTP;
11.9 HTTP 2.0;
Chapter 12: Resource Description and Linked Data;
12.1 RDF;
12.2 When to Use the Description Strategy;
12.3 Resource Types;
12.4 RDF Schema;
12.5 The Linked Data Movement;
12.6 JSON-LD;
12.7 Hydra;
12.8 The XRD Family;
12.9 The Ontology Zoo;
12.10 Conclusion: The Description Strategy Lives!;
Chapter 13: CoAP: REST for Embedded Systems;
13.1 A CoAP Request;
13.2 A CoAP Response;
13.3 Kinds of Messages;
13.4 Delayed Response;
13.5 Multicast Messages;
13.6 The CoRE Link Format;
13.7 Conclusion: REST Without HTTP;
The Status Codex;
Problem Detail Documents;
Families of Status Codes;
Four Status Codes: The Bare Minimum;
1xx: Informational;
2xx: Successful;
3xx: Redirection;
4xx: Client-Side Error;
5xx: Server-Side Error;
The Header Codex;
Custom HTTP Headers;
The Headers;
An API Designer’s Guide to the Fielding Dissertation;
Architectural Properties of the Web;
Interface Constraints;
Architectural Constraints;
Summary;
Conclusion;
Glossary;
Index;
Colophon;