Twelve Patterns to Create Evolvable APIs Mike Amundsen API Academy - - PowerPoint PPT Presentation

▶
twelve patterns to create evolvable apis
SMART_READER_LITE
LIVE PREVIEW

Twelve Patterns to Create Evolvable APIs Mike Amundsen API Academy - - PowerPoint PPT Presentation

Sep 17, 2023 699 likes •2.07k views

Twelve Patterns to Create Evolvable APIs Mike Amundsen API Academy / CA @mamund Drawings by Diogo Lucas @diogoclucas #mcaTravels http://apiacademy.co ? I want to be able to... 1. Change/Add Objects (payloads) 2. Change/Add Addresses

slide-1
SLIDE 1

Twelve Patterns to Create Evolvable APIs

Mike Amundsen API Academy / CA @mamund

Drawings by Diogo Lucas @diogoclucas

slide-2
SLIDE 2
slide-3
SLIDE 3

#mcaTravels

slide-4
SLIDE 4

http://apiacademy.co

slide-5
SLIDE 5
slide-6
SLIDE 6
slide-7
SLIDE 7
slide-8
SLIDE 8
slide-9
SLIDE 9
slide-10
SLIDE 10
slide-11
SLIDE 11

?

slide-12
SLIDE 12
slide-13
SLIDE 13
slide-14
SLIDE 14
slide-15
SLIDE 15
slide-16
SLIDE 16
slide-17
SLIDE 17
slide-18
SLIDE 18
slide-19
SLIDE 19

I want to be able to...

  • 1. Change/Add Objects (payloads)
  • 2. Change/Add Addresses (URLs)
  • 3. Change/Add Actions (links and forms)
slide-20
SLIDE 20

The OAA Challenge

  • 1. Change/Add Objects (payloads)
  • 2. Change/Add Addresses (URLs)
  • 3. Change/Add Actions (links and forms)
slide-21
SLIDE 21

The OAA Challenge

  • 1. Change/Add Objects (payloads)
  • 2. Change/Add Addresses (URLs)
  • 3. Change/Add Actions (links and forms)

"[A] dynamic system that has extreme late binding in all aspects." -- Alan Kay, 2003

slide-22
SLIDE 22

Evolvable API Patterns

slide-23
SLIDE 23

Twelve Patterns for Evolvable APIs

Four Design Patterns Four Basic Principles Four Shared Agreements

slide-24
SLIDE 24

Design Patterns

slide-25
SLIDE 25

Design Patterns

1.PASS MESSAGES, NOT OBJECTS 2.SHARE VOCABULARIES, NOT MODELS 3.USE THE REPRESENTOR PATTERN 4.PUBLISH PROFILES

slide-26
SLIDE 26
slide-27
SLIDE 27

Pass Messages, Not Objects

"I'm sorry that coined the term 'objects' for this

  • topic. The big idea is 'messaging'."

Alan Kay, 1998

slide-28
SLIDE 28
slide-29
SLIDE 29

Pass Messages, Not Objects

Bodies SHOULD be sent using a highly-structured metadata-rich format such as: HAL Collection+JSON Siren UBER Atom, etc.

slide-30
SLIDE 30
slide-31
SLIDE 31

Pass Messages, not Objects

What problem does this solve? I don’t need to share your object model to interact with you. Machines can now manage their own internal models independently.

slide-32
SLIDE 32
slide-33
SLIDE 33

Share Vocabularies, Not Models

"It is easier to standardize representation and relation types than objects and object-specific interfaces."

  • - Roy Fielding
slide-34
SLIDE 34
slide-35
SLIDE 35

Share Vocabularies, Not Models

All messages SHOULD rely only on standardized identifiers (for data/action) based on shared vocabularies. IANA Link Relation Values Schema.org Microformats Dublin Core Activity Streams

slide-36
SLIDE 36
slide-37
SLIDE 37
slide-38
SLIDE 38
slide-39
SLIDE 39

Share Vocabularies, Not Models

What problem does this solve? Vocabulary is how we “evaluate and select” Machines can now evaluate and select without direct human interaction.

slide-40
SLIDE 40
slide-41
SLIDE 41

Use the Representor Pattern

"Use a special filter, a Message Translator, between other filters or applications to translate

  • ne data format into another."
  • Gregor Hohpe
slide-42
SLIDE 42

Use the Representor Pattern

You SHOULD implement a message translator to convert internal models into public messages. Standard Resource Model (WeSTL) Strategy Messages Format Dispatch

slide-43
SLIDE 43
slide-44
SLIDE 44
slide-45
SLIDE 45

Use the Representor Pattern

What problem does this solve? Sometimes we need to translate our conversations in order to communicate. Machines can now “negotiate” the language of a conversation.

slide-46
SLIDE 46
slide-47
SLIDE 47

Publish Profiles

"Profiles provide a way to create a ubiquitous language for talking about APIs (resources) for both humans and machines."

  • - Mark Foster
slide-48
SLIDE 48

Publish Profiles

All messages SHOULD be accompanied by

  • ne or more PROFILE identifiers.

Define all possible data and actions Use Profile Standard (RFC6906) Servers emit profile URI Clients validate profile URI

slide-49
SLIDE 49
slide-50
SLIDE 50
slide-51
SLIDE 51
slide-52
SLIDE 52
slide-53
SLIDE 53

Publish Profiles

What problem does this solve? I need to know what we’re talking about. Machines can now validate domain topics easily

slide-54
SLIDE 54

Messages

slide-55
SLIDE 55

Norman's Action Lifecycle

Donald Norman

slide-56
SLIDE 56

Employing the RPW Loop

slide-57
SLIDE 57

Design loosely-coupled interoperable services

slide-58
SLIDE 58

Basic Principles

slide-59
SLIDE 59

Basic Principles

  • 5. MUST IGNORE
  • 6. MUST FORWARD
  • 7. PROVIDE MRU
  • 8. USE IDEMPOTENCE
slide-60
SLIDE 60
slide-61
SLIDE 61

Must Ignore

“The main goal of the MUST IGNORE pattern

  • f extensibility is to allow backwards- and

forwards-compatible changes.”

  • David Orchard
slide-62
SLIDE 62
slide-63
SLIDE 63

Must Ignore

Clients MUST IGNORE any data/inputs that the client does not understand.

slide-64
SLIDE 64
slide-65
SLIDE 65

Must Ignore

What problem does this solve? Ignoring what we don’t understand lets us “do

  • ur own thing” w/o knowing everyone’s job

Machines can now focus on their

  • wn job, not everyone’s job.
slide-66
SLIDE 66
slide-67
SLIDE 67

MUST FORWARD

“A proxy MUST forward unrecognized header fields…”

  • - RFC 7230

A proxy MUST forward an unknown header A proxy MUST forward unrecognized header fields

slide-68
SLIDE 68
slide-69
SLIDE 69

Must Forward

Clients MUST FORWARD (unchanged) any input fields (URL or FORM) that the client does not recognize.

slide-70
SLIDE 70
slide-71
SLIDE 71

Must Forward

What problem does this solve? We don’t edit for others around us. Machines can now co-operate w/o full understanding of other’s work

slide-72
SLIDE 72
slide-73
SLIDE 73

Provide MRU (Most-Recently-Used)

“A feature of convenience allowing users to quickly see and access the last few used files and documents.”

  • - Wikipedia
slide-74
SLIDE 74
slide-75
SLIDE 75
slide-76
SLIDE 76

Provide MRU

Services SHOULD return the most recently-used (MRU) LINKS and FORMS in all responses.

slide-77
SLIDE 77
slide-78
SLIDE 78
slide-79
SLIDE 79

Provide MRU

What problem does this solve? We need most-used tools close at hand Machines can now find most-used affordances easily

slide-80
SLIDE 80
slide-81
SLIDE 81

Use Idempotence

“Can be applied multiple times without changing the result beyond the initial application.”

  • - Wikpedia
slide-82
SLIDE 82
slide-83
SLIDE 83

Use Idempotence

All network requests SHOULD be idempotent in

  • rder to allow clients to safely repeat them

when response is unclear.

slide-84
SLIDE 84
slide-85
SLIDE 85

Use Idempotence

What problem does this solve? If things didn’t work right the first time, we need to try again. Machines can now safely “try again”

slide-86
SLIDE 86

Networks

slide-87
SLIDE 87

"Data on the Inside vs. Data on the Outside, Helland (2005) http://cidrdb.org/cidr2005/papers/P12.pdf

Programming the Network

Pat Helland

slide-88
SLIDE 88

"Data on the Inside vs. Data on the Outside, Helland (2005) http://cidrdb.org/cidr2005/papers/P12.pdf

Programming the Network

Pat Helland

slide-89
SLIDE 89

"Data on the Inside vs. Data on the Outside, Helland (2005) http://cidrdb.org/cidr2005/papers/P12.pdf

Programming the Network

Pat Helland

slide-90
SLIDE 90

Build Network-Aware Implementations

slide-91
SLIDE 91

Shared Agreements

slide-92
SLIDE 92

Shared Agreements

  • 9. USE RELATED
  • 10. USE NAVIGATION
  • 11. PARTIAL SUBMIT
  • 12. STATE WATCH
slide-93
SLIDE 93
slide-94
SLIDE 94

Use Related

“By watching what you click on in search results, Google can learn that you favor particular sites.” – Danny Sullivan, 2009

slide-95
SLIDE 95
slide-96
SLIDE 96

Use Related

Services SHOULD return a RELATED LINK that responds with ALL the possible actions for this context.

slide-97
SLIDE 97
slide-98
SLIDE 98
slide-99
SLIDE 99

Use Related

What problem does this solve? I can’t remember everything, need an easy way to look up instructions. Machines can now “look up” the available affordances.

slide-100
SLIDE 100
slide-101
SLIDE 101

Use Navigation

“To achieve a single goal which can be broken down into dependable sub-tasks.”

  • - Design Patterns (@uipatterns)
slide-102
SLIDE 102
slide-103
SLIDE 103

Use Navigation

Services SHOULD provide "next/previous" LINK to handle multi-step workflow with "cancel", "restart", & "done."

slide-104
SLIDE 104
slide-105
SLIDE 105

Use Navigation

What problem does this solve? I can’t keep all the steps in my head Machines can now navigate through a long series of steps safely.

slide-106
SLIDE 106
slide-107
SLIDE 107

Partial Submit

“Think of the actions as approximations of what is desired.”

  • - Donald Norman
slide-108
SLIDE 108
slide-109
SLIDE 109

Partial Submit

Services SHOULD accept partially filled-in FORM and return a new FORM with the remaining fields.

slide-110
SLIDE 110
slide-111
SLIDE 111

Partial Submit

What problem does this solve? I sometimes only know part of the story. Machines can now interact in small parts and not always be perfect.

slide-112
SLIDE 112
slide-113
SLIDE 113

State Watch

“Data representing variables in a dynamical system…”

  • - Jens Rassmussen
slide-114
SLIDE 114

State Watch

“Data representing variables in a dynamical system…”

  • - Jens Rassmussen
slide-115
SLIDE 115
slide-116
SLIDE 116

State Watch

Services SHOULD allow clients to subscribe to WATCH VALUES so that clients can determine "done."

slide-117
SLIDE 117
slide-118
SLIDE 118

Use State Watch

What problem does this solve? My boss doesn’t always set my goals. Machines can now set their own goals and act accordingly.

slide-119
SLIDE 119

Hypermedia Affordance

slide-120
SLIDE 120

By Dgies - Own work, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=13691666

The words hypertext, hyperlink, and hypermedia were coined by Ted Nelson around 1965.

Ted Nelson's hyperlinks (1965)

Ted Nelson

slide-121
SLIDE 121

What is Hypermedia?

[Hypermedia] is not constrained to be linear. Hypertext is text which contains links to other texts.

https://www.w3.org/WhatIs.html

slide-122
SLIDE 122

Affordances

"The affordances of the environment are what it offers ... what it provides or furnishes, either for good or ill. James Gibson, 1977

James Gibson

Ecological Approach to Visual Perception, Gibson, 1979

slide-123
SLIDE 123

Affordances

“When I say Hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions.” Roy Fielding, 2008

Roy Fielding

Architectural Styles and the Design of Network-based Software Architectures, Fielding, 2001

slide-124
SLIDE 124

Affordances are the reason for hypermedia

slide-125
SLIDE 125

Enable Connected Services

slide-126
SLIDE 126

Summary

slide-127
SLIDE 127

Programming the Network brings new challenges

slide-128
SLIDE 128

Twelve Patterns for Evolvable APIs

Four Design Patterns Four Basic Principles Four Shared Agreements

slide-129
SLIDE 129

Design Patterns (for interop)

1.PASS MESSAGES, NOT OBJECTS 2.SHARE VOCABULARIES, NOT MODELS 3.THE REPRESENTOR PATTERN 4.PUBLISH PROFILES

slide-130
SLIDE 130

Basic Principles (for networks)

  • 5. MUST IGNORE
  • 6. MUST FORWARD
  • 7. PROVIDE MRU
  • 8. USE IDEMPOTENCE
slide-131
SLIDE 131

Shared Agreements (for services)

  • 9. USE RELATED
  • 10. USE NAVIGATION
  • 11. PARTIAL SUBMIT
  • 12. STATE WATCH
slide-132
SLIDE 132

http://g.mamund.com/12-patterns

slide-133
SLIDE 133
slide-134
SLIDE 134
slide-135
SLIDE 135
slide-136
SLIDE 136

Twelve Patterns to Create Evolvable APIs

Mike Amundsen API Academy / CA @mamund

Drawings by Diogo Lucas @diogoclucas