Tài liệu Building Hypermedia APIs with HTML5 and Node doc

LINK DOWNLOAD MIỄN PHÍ TÀI LIỆU "Tài liệu Building Hypermedia APIs with HTML5 and Node doc": http://123doc.vn/document/1045374-tai-lieu-building-hypermedia-apis-with-html5-and-node-doc.htm

“The human mind operates by association.
With one item in its grasp, it snaps instantly to the
next that is suggested by the association of
thoughts, in accordance with some intricate web
of trails carried by the cells of the brain.”
—Vannevar Bush, 1945
“If computers are the wave of the future, displays
are the surfboards”.
—Ted Nelson, 1974
“HyperText is a way to link and access informa-
tion of various kinds as a web of nodes in which
the user can browse at will.”
—Tim Berners-Lee, 1992
“Hypermedia is defined by the presence of appli-
cation control information embedded within, or
as a layer above, the presentation of information.”
—Roy T. Fielding, 2001
“The WWW is fundamentally a distributed hy-
permedia application.”
—Richard Taylor, 2010

Table of Contents
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
1. Understanding Hypermedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
HTTP, MIME, and Hypermedia 2
HTTP Is the Transfer Protocol 3
MIME Is the Media Type Standard 3
Hypermedia Is the Engine 5
Programming the Web with Hypermedia APIs 6
The Type-Marshaling Dilemma 7
The Hypermedia Solution 10
Identifying Hypermedia : H-Factors 13
Link Factors 15
Control Factors 17
Hypermedia Design Elements 20
Base Format 21
State Transfer 24
Domain Style 26
Application Flow 29
Summary 33
What’s Next? 34
2. XML Hypermedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Scenario 35
Designing the Maze XML Media Type 36
Identifying the State Transitions 36
Selecting the Basic Design Elements 37
The Maze+XML Document 38
Sample Data 42
The Server Code 43
v
The Collection State Response 43
The Item State Response 43
The Cell State Response 44
The Exit State Response 45
The Client Code 46
Maze Game Example 46
Maze Bot Example 51
Summary 56
3. JSON Hypermedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Scenario 57
Designing the Collection+JSON Media-Type 58
Identifying the State Transitions 58
Selecting the Basic Design Elements 59
The Collection+JSON Document 60
The Tasks Application Semantics 64
The Data Model 66
The Write Template 67
Predefined Queries 67
Sample Data 68
Task Documents 69
Design Document 69
The Server Code 71
The Collection Response 71
The Item Response 72
The Query Representations 73
Handling Template Writes 75
The Client Code 77
The Tasks SPI Example 77
The Tasks Command Line Example 88
Summary 92
4.
HTML5 Hypermedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Scenario 95
Designing the Microblog Media Type 96
Expressing Application Domain Semantics in HTML5 96
Identifying the State Transitions 98
Selecting the Basic Design Elements 103
The Microblog Application Profile 104
Sample Data 110
User Documents 110
Message Documents 110
Follow Documents 111
vi | Table of Contents
Design Document 111
The Server Code 113
Authenticating Users 113
Registering a New User 114
Message Responses 116
User Responses 119
The Client Code 122
The POSH Example 122
The Ajax QuoteBot Example 125
Summary 134
5. Documenting Hypermedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Requirements, Compliance, and RFC 2119 135
The RFC 2119 Keywords 136
Sample Documentation Using RFC 2119 Keywords 137
Defining Compliance 137
Documenting Media Type Designs 138
General Layout 138
Documenting XML Designs 143
Documenting JSON Designs 144
Documenting HTML Designs 146
Documenting Application Domain Specifics 148
Publishing Media Type Designs 152
Extending and Versioning Media Types 152
Extending 153
Versioning 154
Registering Media Types and Link Relations 157
Media Types 157
Link Relation Types 159
Design and Implementation Tips 162
Joshua Bloch’s Characteristics of a Good API 162
Roy Fielding’s Hypertext API Guidelines 163
Jon Postel’s Robustness Principle 164
Other Considerations 165
Afterword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
A. References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
B. Additional Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
C.
Maze+XML Media Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Table of Contents | vii
D. Collection+JSON Media Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
E. Microblogging HTML Semantic Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
F. IANA Media Type Registration Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
G. IETF Link Relations Internet Draft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
H. Source Code, Software, and Installation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
viii | Table of Contents
Foreword
You can’t talk about something if you don’t have the words.
The World Wide Web is driven by hypermedia: the ability of a document to describe
its possible states, and its relationship to other documents. Hypermedia is not just a
way of making websites that average people can use; it’s a new style for distributed
computing, powerful and flexible.
There’s nothing new about the web technologies or the hypermedia concept: in another
world, we could have been using hypermedia for distributed computing since the
mid-1990s. Instead, we’ve been slow to adopt hypermedia for anything but consumer
use. It’s an easy concept to grasp intuitively—we all use the Web—but it’s difficult to
understand in a context of development.
Our problems stem from conceptual blocks. The Web invaded our everyday lives years
before its architecture was formally described. We’ve spent the twenty-first century
making gradual progress, coming up with new vocabulary to help developers come to
terms with the power of the Web—power that was there all along.
The description of hypermedia you’ll read in this book is, in my opinion, one of the
biggest conceptual advances since Roy Fielding first defined the REST architectural
style. Mike Amundsen has taken the blanket term “hypermedia” and taken it apart to
see exactly what it can mean and how it works.
What makes a data format useful for some applications and not others? Why is HTML
so versatile, even for nonconsumer applications, and where does it fall short? Under
Mike’s view of hypermedia, these questions have precise answers—answers that I hope
will drive the next generation of web services and web-based technologies.
Mike has not only found the words to describe hypermedia, he’s given voice to our
intuitions about how it works.
—Leonard Richardson, November 2011
ix

Preface
When you set out on your journey to Ithaca,
pray that the road is long, full of adventure,
full of knowledge.
- Constantine P. Cavafy
Hypermedia API Design
This book’s primary focus is on designing hypermedia APIs. That may seem a bit
strange to some readers. There are many books on programming languages, data stor-
age systems, web frameworks, etc. This is not one of those books. Instead, this book
covers the nature of the messages passed between client and server, and how to improve
the content and value of those messages. I, personally, find this to be an exciting and
fascinating area.
As of this writing anecdotal trends seem to indicate an ever-increasing reliance on APIs
in web development. In general, this is a good thing. It means more and more developers
are catching on to the notion that the World Wide Web is a great place to share not
only data, but also services, a goal of those who championed the web in its early days.
However, I believe that this explosion of web APIs may lead us down a troublesome
path. In my experience over the last few years, I have seen too many examples of im-
plementations that rely on concepts of APIs rooted in desktop and local area network
patterns that will not scale well at the WWW level, solutions still exhibiting brittleness
that can lead to costly and frustrating maintenance issues as time goes by. In short, I
don’t see enough hypermedia in API offerings for the web.
This book is an attempt to improve the chances that new APIs added to the WWW
will be easier to use and maintain over time, and that they will take their cue from those
who were responsible for the discovery of the value of hypermedia linking; the codifi-
cation of the HTTP protocol; and the implementation of HTML, Atom/AtomPub, and
other native hypermedia formats that still drive the growth of the web today.
xi
Intended Audience
The primary goal of this book is to increase both the quantity and quality of hypermedia
content in use on the web. To that end, the audience for this text is two-fold.
First, this book is offered as a guide to system architects. Hopefully the text can be a
valuable guide for those responsible for designing systems that rely on hypermedia to
improve the evolvability and stability of long-lived implementations. When viewed as
an integral part of system architecture, hypermedia provides a wealth of possibilities
to architects. Hopefully this book will illustrate that, by treating hypermedia data as a
key architectural component (rather than merely a payload to be pushed about by
clients and servers), architects can increase future stability and flexibility of their sys-
tems.
Second, readers tasked with implementing clients and servers will find valuable advice
and examples on how to deal with hypermedia messages themselves. Up to now, most
books on web implementations have focused too often on the role of servers in dealing
hypermedia. It is the author’s view that this oversight too often results in improper
client implementations that not only ignore, but often negate the value of hypermedia
messages on the web. One of the key advantages of hypermedia as an architectural
pillar is that hypermedia encourages clients to “code for the media type” instead of
writing applications that treat messages as simple data. Writing hypermedia-aware cli-
ents is a skill that takes time to master. And while this book does not focus solely on
writing hypermedia clients, the author hopes that it will show enough examples and
advantages as to spur other, more talented individuals to establish new practices and
techniques aimed at taking direct advantage of hypermedia.
What Is Not Covered
While the examples in this book use HTML5, Node.js, and CouchDB, this book should
not be used as a source for learning these technologies. Astute readers may find the
author’s use of these tools—HTML5, Node.js, CouchDB—somewhat stilted and pos-
sibly, to some, blasphemous. The author makes no claims at expertise in these tech-
nologies. Instead, in the context of this book, they are used as tools for illustrating
points about hypermedia design and implementation. The appendices list several good
books on the technologies used in the writing of this text that the reader is encouraged
to refer to for a more authoritative voice on these matters.
This book does not cover the details of the HTTP protocol and associated web stand-
ards. There is a wealth of writing available and the appendices reference important
RFCs and other standards documents used while preparing this text. The reader will
also find several book recommendations in the appendices well worth the time to read
and become acquainted.
xii | Preface