RESTful Web APIs Praise for “This book is the best place to start learning the essential craft of API Design.” —Matt McLarty Cofounder, API Academy “The entire time I read this book, I was cursing. I was cursing because as I read each explanation, I was worried that they were so good that it would be hard to find a better one to use in my own writing. You will not find another work that explores the topic so thoroughly yet explains the topic so clearly. Please, take these tools, build something fantastic, and share it with the rest of the world, okay?” —Steve Klabnik Author, Designing Hypermedia APIs “Wonderfully thorough treatment of hypermedia formats, REST’s least well understood tenet." —Stefan Tilkov REST evangelist, author, and consultant “The best practical guide to hypermedia APIs. A must-have.” — Ruben Verborgh Semantic hypermedia researcher RESTful Web APIs Leonard Richardson and Mike Amundsen Foreword by Sam Ruby RESTful Web APIs by Leonard Richardson and Mike Amundsen with a Foreword by Sam Ruby Copyright © 2013 Leonard Richardson, amundsen.com, Inc., and Sam Ruby. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/ institutional sales department: 800-998-9938 or [email protected]. Editors: Simon St. Laurent and Meghan Blanchette Indexer: Judith McConville Production Editor: Christopher Hearse Cover Designer: Randy Comer Copyeditor: Jasmine Kwityn Interior Designer: David Futato Proofreader: Linley Dolby Illustrator: Rebecca Demarest September 2013: First Edition Revision History for the First Edition: 2013-09-10: First release See http://oreilly.com/catalog/errata.csp?isbn=9781449358068 for release details. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. RESTful Web APIs, the image of Hoffmann’s two-toed sloth, and related trade dress are trade‐ marks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trade‐ mark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. ISBN: 978-1-449-35806-8 [LSI] For Sienna, Dalton, and Maggie. —Leonard For Milo “The Supervisor,” my constant and patient companion throughout this and so many other projects. Thanks, buddy! —Mike Table of Contents Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv 1. Surfing the Web. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Episode 1: The Billboard 2 Resources and Representations 2 Addressability 3 Episode 2: The Home Page 3 Short Sessions 4 Self-Descriptive Messages 5 Episode 3: The Link 6 Standardized Methods 8 Episode 4: The Form and the Redirect 9 Application State 10 Resource State 11 Connectedness 13 The Web Is Something Special 14 Web APIs Lag Behind the Web 15 The Semantic Challenge 16 2. A Simple API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 HTTP GET: Your Safe Bet 18 How to Read an HTTP Response 18 JSON 20 Collection+JSON 21 Writing to an API 22 HTTP POST: How Resources Are Born 24 Liberated by Constraints 25 v Application Semantics Create the Semantic Gap 27 3. Resources and Representations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 A Resource Can Be Anything 30 A Representation Describes Resource State 30 Representations Are Transferred Back and Forth 31 Resources with Many Representations 32 The Protocol Semantics of HTTP 33 GET 34 DELETE 35 Idempotence 36 POST-to-Append 37 PUT 37 PATCH 38 LINK and UNLINK 39 HEAD 40 OPTIONS 40 Overloaded POST 41 Which Methods Should You Use? 42 4. Hypermedia. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 HTML as a Hypermedia Format 46 URI Templates 49 URI Versus URL 50 The Link Header 51 What Hypermedia Is For 52 Guiding the Request 52 Promises About the Response 53 Workflow Control 54 Beware of Fake Hypermedia! 55 The Semantic Challenge: How Are We Doing? 56 5. Domain-Specific Designs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Maze+XML: A Domain-Specific Design 60 How Maze+XML Works 61 Link Relations 62 Follow a Link to Change Application State 64 The Collection of Mazes 65 Is Maze+XML an API? 67 Client #1: The Game 68 A Maze+XML Server 72 Client #2: The Mapmaker 74 vi | Table of Contents