RESTful Web Clients: Enabling Reuse Through Hypermedia

by Mike Amundsen

Overview

Powerful web-based REST and hypermedia-style APIs are becoming more common every day, but instead of applying the same techniques and patterns to hypermedia clients, many developers rely on custom client code. With this practical guide, you’ll learn how to move from one-off implementations to general-purpose client apps that are stable, flexible, and reusable.

Author Mike Amundsen provides extensive background, easy-to-follow examples, illustrative dialogues, and clear recommendations for building effective hypermedia-based client applications. Along the way, you’ll learn how to harness many of the basic principles that underpin the Web.

• Convert HTML-only web apps into a JSON API service
• Overcome the challenges of maintaining plain JSON-style client apps
• Decouple the output format from the internal object model with the representor pattern
• Explore client apps built with HAL—Hypertext Application Language
• Tackle reusable clients with the Request, Parse, Wait Loop (RPW) pattern
• Learn the pros and cons of building client apps with the Siren content type
• Deal with API versioning by adopting a change-over-time aesthetic
• Compare how JSON, HAL, Siren, and Collection+JSON clients handle the Objects/Addresses/Actions Challenge
• Craft a single client application that can consume multiple services

Product Details

ISBN-13:	9781491921852
Publisher:	O'Reilly Media, Incorporated
Publication date:	02/13/2017
Sold by:	Barnes & Noble
Format:	eBook
Pages:	350
File size:	10 MB

About the Author

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. His most recent book is "Building Hypermedia APIs with HTML5 and Node" He also contributed to the book "RESTful Web Services Cookbook" (by Subbu Allamaraju).

Table of Contents

Foreword xiii

Preface xv

Prologue: Well, That Was a Fun Trip, Eh? xxv

Bob, Carol, and BigCo, Inc xxvii

1 Our HTML Roots and Simple Web APIs 31

The Task Processing System (TPS) Web App 34

HTML from the Server 35

Common Web Browser as the Client 38

Observations 39

The Task Services Web API 40

Web API Common Practice 40

Designing the TPS Web API 41

Implementing the TPS Web API 48

Observations 53

Summary 54

References 56

2 JSON Clients 57

The JSON Web API Client 58

Objects 59

Addresses 62

Actions 63

Quick Summary 66

The JSON SPA Client 66

The HTML Container 66

The Top-Level Parse Loop 68

Objects, Addresses, and Actions 69

Dealing with Change 74

Adding a Field and Filter 75

Coding a New Client 78

Summary 80

References 82

3 The Representor Pattern 83

XML or JSON: Pick a Side! 86

The New Crop of Hypermedia Formats 87

The Fallacy of The Right One 89

Refraining the Problem 90

The Representor Pattern 93

Separating Format from Functionality 94

The Selection Algorithm 95

Adapting and Translating 96

A Server-Side Model 99

Handling the HTTP Accept Header 99

Implementing the Message Translator Pattern 100

General Representor Modules 101

The WeSTL Format 101

A Sample Representor 107

Summary 109

References 112

4 HAL Clients 115

The HAL Format 117

Links 119

Objects and Properties 119

Embedded Links and Objects 120

Quick Summary 121

The HAL Representor 122

Links 123

Properties 124

Embedded 125

Sample TPS Output from the HAL Representor 126

The HAL SPA Client 129

The HTML Container 129

The Top-Level Parse Loop 130

Links 133

Embedded 133

Properties 136

Handling Actions for HAL 138

Quick Summary 140

Dealing with Change 140

Adding an Action 141

The HAL-FORMS Extension 144

The Specification 145

The Implementation 147

Summary 148

References 151

5 The Challenge of Reusable Client Apps 153

What Problem Are You Solving? 155

Double Diamond Model of Design 156

Closed Solution Versus Open Solution 156

Modeling Interaction 159

Maldonados Mechanisms 159

Verplank's Humans 161

A Hypermedia Interaction Loop 164

The Request, Parse, Wait Loop 164

Implementing RPW in Code 166

Handling Verplank's KNOW Step 167

Summary 170

References 172

6 Siren Clients 175

The Siren Format 177

Entities 179

Class 180

Properties 180

Links 181

Actions 181

SubEntities 182

Quick Summary 184

The Siren Representor 184

The Top-Level Loop 185

Class 186

Properties 186

Entities 187

Actions 188

Links 190

Sample TPS Output from the Siren Representor 191

The Siren SPA Client 194

The HTML Container 194

The Top-Level Parse Loop 195

Links 196

Entities 197

Properties 199

Actions 202

Quick Summary 204

Dealing with Change 205

Adding the Email Field and Filter 206

Testing the Email Field 207

The Profile Object Description (POD) Extension 211

The POD Specification 211

The Implementation 213

Displaying Objects in Siren Using POD 214

Quick Summary 216

Summary 216

References 218

7 Versioning and the Web 219

Versioning for the Internet 221

TCP/IPs Robustness Principle 222

HTTP's Must Ignore 223

HTML's Backward Compatibility 225

Guidelines for Non-Breaking Changes 226

API Designers 227

Server Implementors 229

Client Implementors 235

Summary 243

References 245

8 Collection+JSON Clients 247

The Collection+JSON Format 249

Links 252

Items 253

Queries 254

Template 255

Error 257

A Quick Summary 257

The Collection+JSON Representor 258

The Top-Level Processing Loop 258

Links 259

Items 260

Queries 262

Template 264

Error 265

The Collection+JSON SPA Client 265

The HTML Container 266

The Top-Level Parse Loop 267

Links 268

Items 270

Queries 272

Template 274

Error 276

Quick Summary 277

Dealing with Change 277

Adding the Note Object to the TPS API 278

Cj and the OAA Challenge 284

Quick Summary 285

Extending Collection+JSON 285

Supporting Improved Input with Cj-Types 286

The Cj-Suggest Extension 290

Quick Summary 294

Summary 294

References 298

9 Hypermedia and Microservices 299

The Unix Philosophy 302

The TPS Microservices at BigCo 303

The Tasks Service with Collection+JSON 304

The User Service with Siren 307

The Notes Service with HAL 311

One Client to Rule Them All 313

The Home Service 314

The Multiformat Client SPA Container 316

The Format-Switching Client UI 318

Summary 325

References 329

Epilogue: Welcome to Your Future 331

A Project List 333

B Tools and Resources 337

Index 341