Designing for Reuse: Creating APIs for the Future Mike Amundsen, - - PowerPoint PPT Presentation

▶
designing for
SMART_READER_LITE
LIVE PREVIEW

Designing for Reuse: Creating APIs for the Future Mike Amundsen, - - PowerPoint PPT Presentation

May 27, 2023 213 likes •1.39k views

Designing for Reuse: Creating APIs for the Future Mike Amundsen, Layer 7 / CA @mamund Introduction The Challenge Versioning Content removed by authors request Content removed by authors request Deprecate version after a year Content

slide-1
SLIDE 1

Designing for Reuse:Creating APIs for the

Future

Mike Amundsen, Layer 7 / CA @mamund

slide-2
SLIDE 2

Introduction

slide-3
SLIDE 3
slide-4
SLIDE 4
slide-5
SLIDE 5
slide-6
SLIDE 6

The Challenge

slide-7
SLIDE 7
slide-8
SLIDE 8
slide-9
SLIDE 9

Versioning

slide-10
SLIDE 10
slide-11
SLIDE 11

Content removed by author’s request

slide-12
SLIDE 12

Content removed by author’s request

slide-13
SLIDE 13
slide-14
SLIDE 14

Deprecate version after a year

slide-15
SLIDE 15

Content removed by author’s request

slide-16
SLIDE 16

Content removed by author’s request

slide-17
SLIDE 17
slide-18
SLIDE 18

They release a new version every 120 days

slide-19
SLIDE 19

Currently supporting 20+ parallel versions

slide-20
SLIDE 20

Content removed by author’s request

slide-21
SLIDE 21

Content removed by author’s request

slide-22
SLIDE 22
slide-23
SLIDE 23

No breaking changes

slide-24
SLIDE 24

Content removed by author’s request

slide-25
SLIDE 25

To Version means "to turn"

slide-26
SLIDE 26
slide-27
SLIDE 27

There's another word for backward- compatible versioning...

slide-28
SLIDE 28
slide-29
SLIDE 29

Backward-compatible versioning is essentially creating extensions

slide-30
SLIDE 30
slide-31
SLIDE 31

So, how do you enable backward- compatible API extensions?

slide-32
SLIDE 32

I'll talk about two ways today...

slide-33
SLIDE 33

Messages (on the wire)...

slide-34
SLIDE 34

Implementation (in the code)

slide-35
SLIDE 35

Message Design

slide-36
SLIDE 36

Extending Messages

slide-37
SLIDE 37

Extending Messages

slide-38
SLIDE 38

Extending messages let's you easily add backward-compatible changes

slide-39
SLIDE 39

Structure vs Data

slide-40
SLIDE 40

Structure vs Data

slide-41
SLIDE 41

Focus on passing data, not structure

slide-42
SLIDE 42
slide-43
SLIDE 43

There are several new formats designed specifically for passing data

  • n the Web
slide-44
SLIDE 44
slide-45
SLIDE 45
slide-46
SLIDE 46
slide-47
SLIDE 47
slide-48
SLIDE 48
slide-49
SLIDE 49

What's the common theme in these new designs?

slide-50
SLIDE 50

Message over Object

slide-51
SLIDE 51

"[I]t is far easier to standardize representation and relation types than it is to standardize objects and

  • bject-specific

interfaces."

  • Roy T. Fielding
slide-52
SLIDE 52

The most common data-passing format

  • n the Web is…
slide-53
SLIDE 53

The most common data-passing format

  • n the Web is…
slide-54
SLIDE 54
slide-55
SLIDE 55

Because it is easy to extend.

slide-56
SLIDE 56

Message design is not the only place to plan for extensions

slide-57
SLIDE 57

Implementation Design

slide-58
SLIDE 58

Component != Connector

slide-59
SLIDE 59

Component

▪ Database ▪ File System ▪ Message Queue ▪ Transaction Manager ▪ Source Code

slide-60
SLIDE 60

Component == IP

slide-61
SLIDE 61

Component == $$$

slide-62
SLIDE 62

Component == Private

slide-63
SLIDE 63

Connector

▪ Web Server ▪ Browser Agent ▪ Proxy Server ▪ Shared Cache

slide-64
SLIDE 64

Connector == Shared Tech

slide-65
SLIDE 65

Connector == Commodity

slide-66
SLIDE 66

Connector == Public

slide-67
SLIDE 67

Keep Connectors and Components separated

slide-68
SLIDE 68

Implementation Stack

slide-69
SLIDE 69

Implementation Stack

slide-70
SLIDE 70

Implementation Stack

slide-71
SLIDE 71

Implementation Stack

slide-72
SLIDE 72

Class Schedule Server

slide-73
SLIDE 73
slide-74
SLIDE 74
slide-75
SLIDE 75
slide-76
SLIDE 76
slide-77
SLIDE 77
slide-78
SLIDE 78
slide-79
SLIDE 79

Each of these implmentation elements can be updated independently w/o breakage

slide-80
SLIDE 80

Client Strategies

slide-81
SLIDE 81

Most client apps are bound to URIs and the CRUD pattern

slide-82
SLIDE 82

URI-Style Clients (CRUD)

  • HTML SPA Container
slide-83
SLIDE 83

URI-Style Clients (CRUD)

  • URIs, Objects, and Actions
slide-84
SLIDE 84

URI-Style Clients (CRUD)

  • URIs, Objects, and Actions
slide-85
SLIDE 85

URI-Style Clients (CRUD)

  • URIs, Objects, and Actions
slide-86
SLIDE 86

URI-Style Clients (CRUD)

  • Composed HTML
slide-87
SLIDE 87

URI-Style Clients (CRUD)

  • JS Summary
slide-88
SLIDE 88

A better approach is to bind to the message.

slide-89
SLIDE 89

Hypermedia Client (REST)

  • HTML FSM Container
slide-90
SLIDE 90

Hypermedia Client (REST)

  • Media Types and Controls
slide-91
SLIDE 91

Hypermedia Client (REST)

  • Media Types and Controls
slide-92
SLIDE 92

Hypermedia Client (REST)

  • Composed HTML
slide-93
SLIDE 93

Hypermedia Client (REST)

  • Summary JS
slide-94
SLIDE 94

Message over Object

slide-95
SLIDE 95

The Lessons of HTTP

slide-96
SLIDE 96

You never get it right the first time...

slide-97
SLIDE 97
slide-98
SLIDE 98
slide-99
SLIDE 99
slide-100
SLIDE 100
slide-101
SLIDE 101
slide-102
SLIDE 102
slide-103
SLIDE 103
slide-104
SLIDE 104
slide-105
SLIDE 105

So, lots of changes to the protocol over the last 15 years and...

slide-106
SLIDE 106

It's all backward compatible!

slide-107
SLIDE 107

"If you want a protocol to last a few decades, don't assume too much."

  • Roy Fielding
slide-108
SLIDE 108

So the real lesson in all this?

slide-109
SLIDE 109
slide-110
SLIDE 110

So...

slide-111
SLIDE 111
  • Use the extension pattern
  • Keep structure in messages low
  • Consider new message-based media types
  • form-urlencoded is still a winner
  • Commit to no "breaking changes"

Message Design...

slide-112
SLIDE 112
  • Keep component and connectors apart
  • Use representors
  • Make sure storage, biz, representors, and

routers can change w/o breakage

Server Implementation...

slide-113
SLIDE 113
  • Bind to messages, not objects/actions
  • Code defensively, don't assume
  • Make sure requestor can convert messages

into internal objects as needed

Client Implementation...

slide-114
SLIDE 114
  • You won't get it right the first time
  • Build support for extensions into your work
  • If you need to change it once, you might

need to change it often.

The lessons from HTTP

slide-115
SLIDE 115
slide-116
SLIDE 116

Designing for Reuse:Creating APIs for the

Future

Mike Amundsen, Layer 7 / CA @mamund http://g.mamund.com/oscon2014-reuse

Core Hubs:
All Converters PDF Hub Video Hub Audio Hub Image Hub File Compressor