The Costs and Benefits of Building Hypermedia APIs (with Node.js) - - PowerPoint PPT Presentation

▶
the costs and benefits of
SMART_READER_LITE
LIVE PREVIEW

The Costs and Benefits of Building Hypermedia APIs (with Node.js) - - PowerPoint PPT Presentation

Apr 09, 2024 328 likes •1.59k views

Mike Amundsen The Costs and Benefits of Building Hypermedia APIs (with Node.js) Layer 7 Confidential 1 Mike Amundsen Author Presenter Software Explorer Principal API Architect Layer 7 Confidential 2 OK, lets get started

slide-1
SLIDE 1

Layer 7 Confidential 1

Mike Amundsen

The Costs and Benefits of Building Hypermedia APIs (with Node.js)

slide-2
SLIDE 2

Layer 7 Confidential 2

Mike Amundsen

  • Author
  • Presenter
  • Software Explorer
  • Principal API Architect
slide-3
SLIDE 3

Layer 7 Confidential 3

OK, let’s get started…

slide-4
SLIDE 4

Layer 7 Confidential 4

Theonia

"a looking at, viewing, beholding”

slide-5
SLIDE 5

Layer 7 Confidential 5

Theory

"a looking at, viewing, beholding”

slide-6
SLIDE 6

Layer 7 Confidential 6

Praxis

“doing”

slide-7
SLIDE 7

Layer 7 Confidential 7

Practice

“doing”

slide-8
SLIDE 8

Layer 7 Confidential 8

First, a lesson to remember from Donald Norman…

slide-9
SLIDE 9

Layer 7 Confidential 10

Affordances

“The value of a well-designed object, Is when it has such a rich set of affordances, That the people who use it, Can do things with it, That the designer never imagined.”

  • Donald Norman
slide-10
SLIDE 10

Layer 7 Confidential 11

Affordances

“The value of a well-designed object, Is when it has such a rich set of affordances, That the people who use it, Can do things with it, That the designer never imagined.”

  • Donald Norman
slide-11
SLIDE 11

Layer 7 Confidential 12

Affordances

“The value of a well-designed object, Is when it has such a rich set of affordances, That the people who use it, Can do things with it, That the designer never imagined.”

  • Donald Norman
slide-12
SLIDE 12

Layer 7 Confidential 13

Affordances

“The value of a well-designed object, Is when it has such a rich set of affordances, That the people who use it, Can do things with it, That the designer never imagined.”

  • Donald Norman
slide-13
SLIDE 13

Layer 7 Confidential 14

Affordances

“The value of a well-designed object, Is when it has such a rich set of affordances, That the people who use it, Can do things with it, That the designer never imagined.”

  • Donald Norman
slide-14
SLIDE 14

Layer 7 Confidential 15

Some background…

slide-15
SLIDE 15

Layer 7 Confidential 16

Affordances

  • The foundation for perception is ambient,

ecologically available information.

  • Affordances are all "action possibilities" latent in

the environment. Theory of Affordances, 1979

  • James J. Gibson
slide-16
SLIDE 16

Layer 7 Confidential 17

  • Seven Stages of Action

Affordances

The Design of Everyday Things, 1988

  • Donald Norman
slide-17
SLIDE 17

Layer 7 Confidential 18

Affordances

Knowledge (“head” vs. “world”)

April 17, 2012 APIs to Affordances : WS-REST 2012 18

Property Knowledge in the World Knowledge in the Head Learning Learning not required. Interpretation substitutes for learning. How easy it is to interpret information is the world depends upon how well it exploits natural mappings and constraints. Requires learning, which can be considerable. Learning is made easier if there is meaning of structure to the material (or if there is a good mental model). Efficiency

  • f use

Tends to be slowed up by the need to find and interpret the external information. Can be very efficient Ease of use at first encounter High Low

slide-18
SLIDE 18

Layer 7 Confidential 19

Affordances

  • "Hypermedia is defined by the presence of application

control information embedded within, or as a layer above, the presentation of information“ (2001)

  • “When I say [Hypermedia], I mean the simultaneous

presentation of information and controls such that the information becomes the affordance through which the user

  • btains choices and selects actions” (2008)

Architectural Styles and the Design

  • f Network-based Software, 2001
  • Roy T. Fielding
slide-19
SLIDE 19

Layer 7 Confidential 20

Affordances

  • "Hypermedia is defined by the presence of application

control information embedded within, or as a layer above, the presentation of information“ (2001)

  • “When I say [Hypermedia], I mean the simultaneous

presentation of information and controls such that the information becomes the affordance through which the user

  • btains choices and selects actions” (2008)

Architectural Styles and the Design

  • f Network-based Software, 2001
  • Roy T. Fielding
slide-20
SLIDE 20

Layer 7 Confidential 21

Affordances

Affordances make Hypermedia possible.

slide-21
SLIDE 21

Layer 7 Confidential 22

Affordances

Hypermedia can provide a Rich Set of Affordances

slide-22
SLIDE 22

Layer 7 Confidential 23

Maze+XML

Design #1: A big pile of Affordances

slide-23
SLIDE 23

Layer 7 Confidential 24

Maze+XML

  • Maze+XML media type
  • First design in late 2010, registered w/ IANA 2011
  • “…an XML data format for sharing maze state information

between clients and servers. It can be used to implement simple mazes, adventure games, and other related data.”

  • Read-only navigational links
  • Nine link identifiers:

collection, maze, start, exit, current, north, south, east, west

slide-24
SLIDE 24

Layer 7 Confidential 25

Maze+XML

Message

slide-25
SLIDE 25

Layer 7 Confidential 26

Maze+XML Server

slide-26
SLIDE 26

Layer 7 Confidential 27

Maze+XML

Client

slide-27
SLIDE 27

Layer 7 Confidential 28

Maze+XML

Client

slide-28
SLIDE 28

Layer 7 Confidential 29

Maze+XML

Client

slide-29
SLIDE 29

Layer 7 Confidential 30

Maze+XML

Client Code

slide-30
SLIDE 30

Layer 7 Confidential 31

Maze+XML

In the wild…

slide-31
SLIDE 31

Layer 7 Confidential 32

Maze+XML

  • Darrel Miller
  • “A good example of using link relations to convey

domain specific semantics.”

  • “Has been a good test bed for trying to develop a UI

transparently that tracks the state of the user agent as it navigates between representations.”

slide-32
SLIDE 32

Layer 7 Confidential 33

Maze+XML

Darrel Miller – C#

slide-33
SLIDE 33

Layer 7 Confidential 34

  • Yannick Loiseau
  • “I can say that a non-restful architecture would have been a

lot harder to deal with in bash, because hypermedia

  • bviously made the maze exploration really easy”
  • “I think that Link headers would be even

easier to deal with…”

Maze+XML

slide-34
SLIDE 34

Layer 7 Confidential 35

Yannick Loiseau - Python

Maze+XML

slide-35
SLIDE 35

Layer 7 Confidential 36

Yannick Loiseau - Bash

Maze+XML

slide-36
SLIDE 36

Layer 7 Confidential 37

Maze+XML

  • Characteristics
  • Read-Only navigational links
  • Limited set of identifiers
  • Domain specific
  • Benefits
  • Simple, direct design
  • Easy to create servers/clients
  • M2M works when algorithm is available
  • Costs
  • Limited reach
  • M2M clients challenge evolvability
slide-37
SLIDE 37

Layer 7 Confidential 38

H-Factors

“Pardon me, did you say ‘links’?”

slide-38
SLIDE 38

Layer 7 Confidential 39

  • “The H Factor of a media-type is a measure of the

level of hypermedia support within that media-type.”

  • “H Factor values can be used to compare and

contrast media types in order to aid in selecting the proper media-type(s) for your implementation.”

H-Factors

REST: From Research to Practice : Hypermedia Types, 2011

  • Mike Amundsen
slide-39
SLIDE 39

Layer 7 Confidential 40

H-Factors

Analyzing Media Types

slide-40
SLIDE 40

Layer 7 Confidential 41

H-Factors

Analyzing Media Types

slide-41
SLIDE 41

Layer 7 Confidential 42

H-Factors

Analyzing Media Types

slide-42
SLIDE 42

Layer 7 Confidential 43

H-Factors

  • There are five LINK Factors

(LO, LE, LT, LI, LN)

  • There are four CONTROL Factors

(CR, CU, CM, CL)

slide-43
SLIDE 43

Layer 7 Confidential 44

H-Factors

  • There are five LINK Factors

(LO, LE, LT, LI, LN)

  • There are four CONTROL Factors

(CR, CU, CM, CL)

slide-44
SLIDE 44

Layer 7 Confidential 45

H-Factors

Linking

  • Outbound Links (LO)
slide-45
SLIDE 45

Layer 7 Confidential 46

H-Factors

Linking

  • Outbound Links (LO)
  • Embedded Links (LE)
slide-46
SLIDE 46

Layer 7 Confidential 47

H-Factors

Linking

  • Outbound Links (LO)
  • Embedded Links (LE)
  • Templated Links (LT)
slide-47
SLIDE 47

Layer 7 Confidential 48

H-Factors

Linking

  • Outbound Links (LO)
  • Embedded Links (LE)
  • Templated Links (LT)
  • Idempotent Links (LI)
slide-48
SLIDE 48

Layer 7 Confidential 49

H-Factors

Linking

  • Outbound Links (LO)
  • Embedded Links (LE)
  • Templated Links (LT)
  • Idempotent Links (LI)
  • Non-Idempotent Links (LN)
slide-49
SLIDE 49

Layer 7 Confidential 50

H-Factors

  • There are five LINK Factors

(LO, LE, LT, LI, LN)

  • There are four CONTROL Factors

(CR, CU, CM, CL)

slide-50
SLIDE 50

Layer 7 Confidential 51

H-Factors

Control

  • Request Controls (CR)
slide-51
SLIDE 51

Layer 7 Confidential 52

H-Factors

Control

  • Request Controls (CR)
  • Update Controls (CU)
slide-52
SLIDE 52

Layer 7 Confidential 53

H-Factors

Control

  • Request Controls (CR)
  • Update Controls (CU)
  • Method Controls (CM)
slide-53
SLIDE 53

Layer 7 Confidential 54

H-Factors

Control

  • Request Controls (CR)
  • Update Controls (CU)
  • Method Controls (CM)
  • Link Controls (CL)
slide-54
SLIDE 54

Layer 7 Confidential 55

H-Factors

  • A pre-defined collection of H-Factors is called a

“Media Type”

  • Each media type has it’s own “H-Factor” signature.
slide-55
SLIDE 55

Layer 7 Confidential 56

H-Factors

H-Factors document the Affordances

  • f the

Media Type

slide-56
SLIDE 56

Layer 7 Confidential 57

H-Factors

“OK, media types, affordances, I see…

slide-57
SLIDE 57

Layer 7 Confidential 58

Collection+JSON

Design #2: A read/write hypermedia type

slide-58
SLIDE 58

Layer 7 Confidential 59

Collection+JSON

  • Collection+JSON media type
  • First designs in early 2011, registered w/ IANA mid 2011
  • “…a JSON-based read/write hypermedia-type designed to

support management and querying of simple collections.”

  • It’s Atom w/ LT + templated writes
  • Very limited link identifiers
  • collection, item, templates, query
slide-59
SLIDE 59

Layer 7 Confidential 60

Message

Collection+JSON

slide-60
SLIDE 60

Layer 7 Confidential 61

Message

Collection+JSON

slide-61
SLIDE 61

Layer 7 Confidential 62

Message

Collection+JSON

slide-62
SLIDE 62

Layer 7 Confidential 63

Message

Collection+JSON

slide-63
SLIDE 63

Layer 7 Confidential 64

Message

Collection+JSON

slide-64
SLIDE 64

Layer 7 Confidential 65

Server

Collection+JSON

slide-65
SLIDE 65

Layer 7 Confidential 66

Server

Collection+JSON

slide-66
SLIDE 66

Layer 7 Confidential 67

Server

Collection+JSON

slide-67
SLIDE 67

Layer 7 Confidential 68

Client Code

Collection+JSON

slide-68
SLIDE 68

Layer 7 Confidential 69

Client Code

Collection+JSON

slide-69
SLIDE 69

Layer 7 Confidential 70

Client Code

Collection+JSON

slide-70
SLIDE 70

Layer 7 Confidential 71

Client App

Collection+JSON

slide-71
SLIDE 71

Layer 7 Confidential 72

Client App

Collection+JSON

slide-72
SLIDE 72

Layer 7 Confidential 73

Collection+JSON

In the wild…

slide-73
SLIDE 73

Layer 7 Confidential 74

Collection+JSON

  • Nokia Research - Live Mixed Reality - Vlad Stribu
  • “[Collection+JSON] … allows us to develop authoring tools

that have the ability to self-adapt the user interface to the usage context.”

slide-74
SLIDE 74

Layer 7 Confidential 75

Collection+JSON

  • Nokia Research - Live Mixed Reality - Vlad Stribu
  • “Collection+JSON was close enough to what we were

looking for…”

  • “Most important factor that influenced our decision was the

community around this format…”

slide-75
SLIDE 75

Layer 7 Confidential 76

Collection+JSON

  • CloudApp – Larry Marburger
  • “CloudApp allows you to share images, links, music, videos

and files.”

  • “[Due to developer team changes] we had some setbacks

with the Mac app and subsequently the API. We just started working with another developer who's making amazing progress.”

slide-76
SLIDE 76

Layer 7 Confidential 77

Collection+JSON

  • ember.js – Yehuda Katz
  • “A framework for creating ambitious applications.”
  • “By default, it's somewhat repetitive, but that can be

addressed…”

  • “It was straight-forward to extend it with features I needed”
  • “I am starting to feel like with the number of extensions, I

should consider [creating] my own media type.”

slide-77
SLIDE 77

Layer 7 Confidential 78

Collection+JSON

  • Characteristics
  • Read/Write w/ Templates
  • Small set of link identifiers
  • General “List Domain” handler
  • Benefits
  • Limited design means simple parser
  • Servers easy, clients harder
  • Built-in support for custom domain annotations
  • Costs
  • Domain mapping is more difficult
  • M2M clients limited to pre-declared vocabulary
slide-78
SLIDE 78

Layer 7 Confidential 79

Affordance Aspects

“So, are all affordances essentially the same?”

slide-79
SLIDE 79

Layer 7 Confidential 80

Affordance Aspects

  • “For the purposes of applying affordances to

hypermedia, there are four important aspects to consider”

slide-80
SLIDE 80

Layer 7 Confidential 81

Affordance Aspects

  • Safe
  • The HTTP protocol supports a number of "safe"

actions such as HEAD, and GET.

slide-81
SLIDE 81

Layer 7 Confidential 82

Affordance Aspects

  • Safe
  • The HTTP protocol supports a number of "safe"

actions such as HEAD, and GET.

  • The HTTP methods PUT, POST, and DELETE are

categorized as "unsafe" actions.

slide-82
SLIDE 82

Layer 7 Confidential 83

Affordance Aspects

  • Idempotent
  • When an HTML:FORM element has the METHOD

property set to "get" it represents an idempotent action.

slide-83
SLIDE 83

Layer 7 Confidential 84

Affordance Aspects

  • Idempotent
  • When an HTML:FORM element has the METHOD

property set to "get" it represents an idempotent action.

  • When the same property is set to "post" the

affordance represents a non-idempotent action.

slide-84
SLIDE 84

Layer 7 Confidential 85

Affordance Aspects

  • Mutability
  • HTML:FORM affords mutability
slide-85
SLIDE 85

Layer 7 Confidential 86

Affordance Aspects

  • Mutability
  • HTML:FORM affords mutability
  • HTML:LINK is immutable
slide-86
SLIDE 86

Layer 7 Confidential 87

Affordance Aspects

  • Transclusion
  • HTML:IMG affords transclusion
slide-87
SLIDE 87

Layer 7 Confidential 88

Affordance Aspects

  • Transclusion
  • HTML:IMG affords transclusion
  • HTML:A does not
slide-88
SLIDE 88

Layer 7 Confidential 89

Affordance Aspects

  • However, this single affordance is not

very usable.

slide-89
SLIDE 89

Layer 7 Confidential 90

Affordance Aspects

Media types should be usable

slide-90
SLIDE 90

Layer 7 Confidential 91

Affordance Aspects

Messages should be usable

slide-91
SLIDE 91

Layer 7 Confidential 92

Affordance Aspects

APIs should be usable

slide-92
SLIDE 92

Layer 7 Confidential 93

ALPS for HTML

Design #3: Aspects, Factors, Abstractions

slide-93
SLIDE 93

Layer 7 Confidential 94

ALPS for HTML

  • ALPS profile URI
  • First designs in early 2011 (not registered)
  • “The purpose of Application-Level Profile Semantics (ALPS)

is to document the application-level semantics of a particular implementation.”

  • “The example profile here contains details
  • n customizing the XHTML media type

for a specific application domain: Micro-blogging.”

slide-94
SLIDE 94

Layer 7 Confidential 95

ALPS for HTML

  • ALPS profile URI
  • Multiple parties building their own client or server

applications without seeing each other's work or accessing a running "reference" implementation.

  • Developers are expected to rely on the constraints and

definitions found in this document (and the referenced RFCs) as the sole instruction.

slide-95
SLIDE 95

Layer 7 Confidential 96

ALPS for HTML

Messages

slide-96
SLIDE 96

Layer 7 Confidential 97

ALPS for HTML

Messages

slide-97
SLIDE 97

Layer 7 Confidential 98

ALPS for HTML

Messages

slide-98
SLIDE 98

Layer 7 Confidential 99

ALPS for HTML

Server Code

slide-99
SLIDE 99

Layer 7 Confidential 100

ALPS for HTML

Client Code

slide-100
SLIDE 100

Layer 7 Confidential 101

ALPS for HTML

Client App

slide-101
SLIDE 101

Layer 7 Confidential 102

ALPS for HTML

Client Bot

slide-102
SLIDE 102

Layer 7 Confidential 103

ALPS for HTML

Client Bot

slide-103
SLIDE 103

Layer 7 Confidential 104

ALPS for HTML

Client Bot

slide-104
SLIDE 104

Layer 7 Confidential 105

ALPS for HTML

“In the wild…”

slide-105
SLIDE 105

Layer 7 Confidential 106

ALPS for HTML

Rstat.us – Carol Nichols

  • “There are two things that make rstat.us special: simplicity

and openness.”

  • “[S]ince we already have a full-functioning end-user facing

site, the ALPS microblogging spec means adding a few attributes rather than having to maintain a totally separate API interface.”

  • “The current way of

presenting the ALPS spec is [too] flat.”

slide-106
SLIDE 106

Layer 7 Confidential 107

ALPS for HTML

Rstat.us – Carol Nichols

slide-107
SLIDE 107

Layer 7 Confidential 108

ALPS for HTML

Rstat.us – Carol Nichols

slide-108
SLIDE 108

Layer 7 Confidential 109

ALPS for HTML

  • Characteristics
  • Domain Semantics Only
  • Media-type agnostic
  • Benefits
  • Focused on problem domain
  • Treats “pages” as the “API”
  • Costs
  • Very abstract model
  • Tough to document
  • Seems “over complex” esp. for M2M cases
slide-109
SLIDE 109

Layer 7 Confidential 110

ALPS for HTML

“If HTML is not the only media-type we need…”

slide-110
SLIDE 110

Layer 7 Confidential 111

ALPS for HTML

“How do you choose?”

slide-111
SLIDE 111

Layer 7 Confidential 112

Methodology

Mapping your domain to HTTP

slide-112
SLIDE 112

Layer 7 Confidential 113

  • Designing messages is the primary work
  • Focus on mapping to payloads, not identifiers
  • Survey existing media types first
  • If you can’t find a suitable H-Factor signature

match, consider designing your own.

  • Pro Tip: you can always find a match.

Methodology

slide-113
SLIDE 113

Layer 7 Confidential 114

  • Start with a format (XML, JSON, HTML, etc.)
  • You might need to support more than one
  • Don’t assume you can “cross-map” formats easily
  • Pro Tip: you almost always need to support more

than one.

Methodology

slide-114
SLIDE 114

Layer 7 Confidential 115

  • Select your other design elements as needed

Methodology

slide-115
SLIDE 115

Layer 7 Confidential 116

  • Represent State, not Objects
  • Remember both data and transitions
  • Craft lots of messages
  • Pro Tip: you can never have enough messages

Methodology

slide-116
SLIDE 116

Layer 7 Confidential 117

When you are sure you have:

  • The proper format
  • The right H-Factor signature
  • The correct mapping of domain to messages
  • Sufficent message examples

Then, and only then…

Methodology

slide-117
SLIDE 117

Layer 7 Confidential 118

You can start writing the code

Methodology

slide-118
SLIDE 118

Layer 7 Confidential 119

Because…

Methodology

slide-119
SLIDE 119

Layer 7 Confidential 120

The code is only the implementation

Methodology

slide-120
SLIDE 120

Layer 7 Confidential 121

The code is only the implementation The media type is the design.

Methodology

slide-121
SLIDE 121

Layer 7 Confidential 122

And if you get the design right...

Methodology

slide-122
SLIDE 122

Layer 7 Confidential 123

Your users will be able to do things

Methodology

slide-123
SLIDE 123

Layer 7 Confidential 124

Your users will be able to do things

Methodology

slide-124
SLIDE 124

Layer 7 Confidential 125

Your users will be able to do things you never imagined

Methodology

slide-125
SLIDE 125

Layer 7 Confidential 126

Mike Amundsen

The Costs and Benefits of Building Hypermedia APIs (with Node.js)

@mamund