,Part I: Understanding RESTful Hypermedia
The opening chapters (Chapters 1 and 2) describe the foundation that underpins all the recipes in
the book. They are a mix of history, philosophy, and pragmatic thinking. These are the ideas and
principles that reflect the lessons I’ve learned over my years of designing, building, and supporting
network software applications running on the web.
Chapter 1, Introducing RESTful Web APIs
This is a general overview of the rationale behind the selected recipes in this book. It
includes a section answering the question “what are RESTful web APIs (RWAs)?,” reasons
hypermedia plays such an important role in the creation of RWAs, and some base-level
shared principles that guide the selection and explanation of the recipes in this book. This
chapter “sets the table” for all the material that follows.
Chapter 2, Thinking and Designing in Hypermedia
This chapter explores the background of hypermedia-driven distributed systems that form
the foundation for web applications. Each recipe collection covered in Part II (design,
clients, services, data, and workflow) is explored with a mix of history, philosophy, and
pragmatic thinking. Reading this chapter will help you understand some of the key design
ideas and technical bases for all the patterns and practices outlined in the rest of the book.
Part II: Hypermedia Recipe Catalog
Part II holds all the recipes I’ve selected for this volume. You’ll notice that most of the chapters
start with the word “hypermedia.” This should give you a clue to the overall approach we’ll be
taking throughout the book.
Chapter 3, Hypermedia Design
Reliable and resilient services start with thoughtful designs. This chapter covers a set of
common challenges you’ll need to deal with before you even get to the level of coding and
releasing your services. This chapter will be particularly helpful to architects as well as
service designers, and helps set the tone for the various recipes that follow.
Chapter 4, Hypermedia Clients
This chapter focuses on challenges you’ll face when creating service/API consumer
applications. I made a point of discussing client apps before talking about recipes for
service interfaces themselves. A common approach for creating flexible and resilient
service consumers is necessary for any program that plans on creating a stable and reliable
platform for open services that can live on the web as well as within an enterprise.
Chapter 5, Hypermedia Services
, With a solid foundation of design principles and properly architected client applications, it
can be easier to build and release stable service producers that can be safely updated over
time without breaking existing API consumers. This set of recipes focuses not only on
principles of solid service interface design but also on the importance of supporting runtime
error recovery and reliability patterns to make sure your solutions stay up and running even
when parts of your system experience failures.
Chapter 6, Distributed Data
This chapter focuses on the challenges of supporting persisted data in an online, distributed
environment. Most of the recipes here are aimed at improving the responsiveness,
scalability, and reliability of your data services by ensuring data integrity—even when
changing internal data models and implementations at runtime.
Chapter 7, Hypermedia Workflow
The last set of recipes focuses on creating and managing service workflow on the web. The
key challenge to face for open services workflow is to create a safe and reliable set of
solutions for enlisting multiple unrelated services into a single, resilient workflow to solve
a problem none of the individual services knows anything about. I saved this chapter for
last since it relies on many of the recipes covered earlier in the book.
Chapter 8, Closing Remarks
The final chapter is a short wrap-up of the material as well as a “call-forward” to help you
decide on your own “next steps” as you set out to apply these recipes to your environment.
Appendices
There are a series of appendices for the book that you can use as additional support materials.
These are sometimes referred to in the text but can also be treated as stand-alone references.
Appendix A, Guiding Principles
This appendix is a short “motivational poster” version of the single guiding principle
behind the selected recipes, as well as some secondary principles used to shape the
description and, ultimately, the implementation of these patterns in general.
Appendix B, Additional Reading
Throughout the book, I’ll be recommending additional reading, quoting from books and
articles, and calling out presentations and videos that are the source of much of the advice
in the book. This appendix contains a self-standing list of reading and viewing materials
that you can use as references and a guide when working through the recipes.
Appendix C, Related Standards
, Since the goal of this book is to create services that can successfully live “on the web,” the
recipes depend upon a number of important open web standards. This appendix contains a
list of the related standards documents.
Appendix D, Using the HyperCLI
In several places in the book, I reference a command-line interface tool called HyperCLI.
You can use this tool to interact with hypermedia-aware services. This appendix provides
a short introduction to the tool and some pointers to other online resources on how to take
advantage of HyperCLI and HyperLang.
What’s Not Covered
As a book of recipes, this text is not suited for teaching the reader how to implement the patterns
and ideas listed here. If you are new to any of the pillars upon which this book is built, you’ll want
to look to other sources for assistance.
The following books are some that I have used in training and consulting engagements on topics
not covered in detail in this book:
HTTP protocol
Most of the recipes in this book were developed for HTTP protocol implementations. For
more on the power and challenges of HTTP, I recommend the HTTP Developer’s
Handbook by Chris Shiflett (Sams). Shiflett’s text has been a great help to me in learning
the inside details of the HTTP protocol. Published in 2003, it is still a valuable book that I
highly recommend.
API design
For details on designing APIs for distributed services, I suggest readers check out
my Building Hypermedia APIs with HTML5 and Node (O’Reilly). For those looking for a
book focused on coding APIs, my more recent book, Design and Build Great Web
APIs (Pragmatic Bookshelf), offers a detailed hands-on guide to the full API lifecycle.
API clients
The work of coding API/service clients is a skill unto itself. For an extended look at the
process of creating flexible hypermedia-driven client applications, I refer readers to
my RESTful Web Clients (O’Reilly).
Web APIs
For details on creating web APIs themselves, I encourage readers to check out the
book RESTful Web APIs (O’Reilly), which I coauthored with Leonard Richardson, and my
book Design and Build Great Web APIs (O’Reilly). Other books I keep close at hand
The opening chapters (Chapters 1 and 2) describe the foundation that underpins all the recipes in
the book. They are a mix of history, philosophy, and pragmatic thinking. These are the ideas and
principles that reflect the lessons I’ve learned over my years of designing, building, and supporting
network software applications running on the web.
Chapter 1, Introducing RESTful Web APIs
This is a general overview of the rationale behind the selected recipes in this book. It
includes a section answering the question “what are RESTful web APIs (RWAs)?,” reasons
hypermedia plays such an important role in the creation of RWAs, and some base-level
shared principles that guide the selection and explanation of the recipes in this book. This
chapter “sets the table” for all the material that follows.
Chapter 2, Thinking and Designing in Hypermedia
This chapter explores the background of hypermedia-driven distributed systems that form
the foundation for web applications. Each recipe collection covered in Part II (design,
clients, services, data, and workflow) is explored with a mix of history, philosophy, and
pragmatic thinking. Reading this chapter will help you understand some of the key design
ideas and technical bases for all the patterns and practices outlined in the rest of the book.
Part II: Hypermedia Recipe Catalog
Part II holds all the recipes I’ve selected for this volume. You’ll notice that most of the chapters
start with the word “hypermedia.” This should give you a clue to the overall approach we’ll be
taking throughout the book.
Chapter 3, Hypermedia Design
Reliable and resilient services start with thoughtful designs. This chapter covers a set of
common challenges you’ll need to deal with before you even get to the level of coding and
releasing your services. This chapter will be particularly helpful to architects as well as
service designers, and helps set the tone for the various recipes that follow.
Chapter 4, Hypermedia Clients
This chapter focuses on challenges you’ll face when creating service/API consumer
applications. I made a point of discussing client apps before talking about recipes for
service interfaces themselves. A common approach for creating flexible and resilient
service consumers is necessary for any program that plans on creating a stable and reliable
platform for open services that can live on the web as well as within an enterprise.
Chapter 5, Hypermedia Services
, With a solid foundation of design principles and properly architected client applications, it
can be easier to build and release stable service producers that can be safely updated over
time without breaking existing API consumers. This set of recipes focuses not only on
principles of solid service interface design but also on the importance of supporting runtime
error recovery and reliability patterns to make sure your solutions stay up and running even
when parts of your system experience failures.
Chapter 6, Distributed Data
This chapter focuses on the challenges of supporting persisted data in an online, distributed
environment. Most of the recipes here are aimed at improving the responsiveness,
scalability, and reliability of your data services by ensuring data integrity—even when
changing internal data models and implementations at runtime.
Chapter 7, Hypermedia Workflow
The last set of recipes focuses on creating and managing service workflow on the web. The
key challenge to face for open services workflow is to create a safe and reliable set of
solutions for enlisting multiple unrelated services into a single, resilient workflow to solve
a problem none of the individual services knows anything about. I saved this chapter for
last since it relies on many of the recipes covered earlier in the book.
Chapter 8, Closing Remarks
The final chapter is a short wrap-up of the material as well as a “call-forward” to help you
decide on your own “next steps” as you set out to apply these recipes to your environment.
Appendices
There are a series of appendices for the book that you can use as additional support materials.
These are sometimes referred to in the text but can also be treated as stand-alone references.
Appendix A, Guiding Principles
This appendix is a short “motivational poster” version of the single guiding principle
behind the selected recipes, as well as some secondary principles used to shape the
description and, ultimately, the implementation of these patterns in general.
Appendix B, Additional Reading
Throughout the book, I’ll be recommending additional reading, quoting from books and
articles, and calling out presentations and videos that are the source of much of the advice
in the book. This appendix contains a self-standing list of reading and viewing materials
that you can use as references and a guide when working through the recipes.
Appendix C, Related Standards
, Since the goal of this book is to create services that can successfully live “on the web,” the
recipes depend upon a number of important open web standards. This appendix contains a
list of the related standards documents.
Appendix D, Using the HyperCLI
In several places in the book, I reference a command-line interface tool called HyperCLI.
You can use this tool to interact with hypermedia-aware services. This appendix provides
a short introduction to the tool and some pointers to other online resources on how to take
advantage of HyperCLI and HyperLang.
What’s Not Covered
As a book of recipes, this text is not suited for teaching the reader how to implement the patterns
and ideas listed here. If you are new to any of the pillars upon which this book is built, you’ll want
to look to other sources for assistance.
The following books are some that I have used in training and consulting engagements on topics
not covered in detail in this book:
HTTP protocol
Most of the recipes in this book were developed for HTTP protocol implementations. For
more on the power and challenges of HTTP, I recommend the HTTP Developer’s
Handbook by Chris Shiflett (Sams). Shiflett’s text has been a great help to me in learning
the inside details of the HTTP protocol. Published in 2003, it is still a valuable book that I
highly recommend.
API design
For details on designing APIs for distributed services, I suggest readers check out
my Building Hypermedia APIs with HTML5 and Node (O’Reilly). For those looking for a
book focused on coding APIs, my more recent book, Design and Build Great Web
APIs (Pragmatic Bookshelf), offers a detailed hands-on guide to the full API lifecycle.
API clients
The work of coding API/service clients is a skill unto itself. For an extended look at the
process of creating flexible hypermedia-driven client applications, I refer readers to
my RESTful Web Clients (O’Reilly).
Web APIs
For details on creating web APIs themselves, I encourage readers to check out the
book RESTful Web APIs (O’Reilly), which I coauthored with Leonard Richardson, and my
book Design and Build Great Web APIs (O’Reilly). Other books I keep close at hand
