API Design Methodology Mike Amundsen API Academy / CA @mamund - - PowerPoint PPT Presentation

▶
api design methodology
SMART_READER_LITE
LIVE PREVIEW

API Design Methodology Mike Amundsen API Academy / CA @mamund - - PowerPoint PPT Presentation

Dec 28, 2022 323 likes •1.54k views

API Design Methodology Mike Amundsen API Academy / CA @mamund Introduction Learning Hypermedia Clients Focus on the client side code Covers human-driven & M2M Lots of code! Due in fall 2015 @LCHBook #LCHProject

slide-1
SLIDE 1

API Design Methodology

Mike Amundsen API Academy / CA @mamund

slide-2
SLIDE 2

Introduction

slide-3
SLIDE 3
slide-4
SLIDE 4
slide-5
SLIDE 5
slide-6
SLIDE 6
slide-7
SLIDE 7
slide-8
SLIDE 8

Learning Hypermedia Clients

  • Focus on the client side code
  • Covers human-driven & M2M
  • Lots of code!
  • Due in fall 2015
  • @LCHBook #LCHProject
slide-9
SLIDE 9

Hallway Conversations Podcast

Hosted by Phil Japikse, Steve Bohlen, Lee Brandt, James Bender Website: www.hallwayconversations.com iTunes: http://bit.ly/hallway_convo_itunes Feed Burner: http://bit.ly/hallway_convo_feed Also available through Windows Store

slide-10
SLIDE 10

APIs for the Web

slide-11
SLIDE 11
slide-12
SLIDE 12
slide-13
SLIDE 13
slide-14
SLIDE 14
slide-15
SLIDE 15

Actually, we have a methodology already...

slide-16
SLIDE 16

Design Guidelines

  • Craft [good/pretty/usable/stable] URIs
slide-17
SLIDE 17
slide-18
SLIDE 18

Design Guidelines

  • Craft [good/pretty/usable/stable] URIs
  • Map domain actions to HTTP methods (CRUD)
slide-19
SLIDE 19
slide-20
SLIDE 20

Design Guidelines

  • Craft [good/pretty/usable/stable] URIs
  • Map domain actions to HTTP methods (CRUD)
  • Use the proper HTTP Status Codes
slide-21
SLIDE 21
slide-22
SLIDE 22

Design Guidelines

  • Craft [good/pretty/usable/stable] URIs
  • Map domain actions to HTTP methods (CRUD)
  • Use the proper HTTP Status Codes
  • Document serialized objects as HTTP bodies
slide-23
SLIDE 23
slide-24
SLIDE 24

Design Guidelines

  • Craft [good/pretty/usable/stable] URIs
  • Map domain actions to HTTP methods (CRUD)
  • Use the proper HTTP Status Codes
  • Document serialized objects as HTTP bodies
  • Use HTTP headers responsibly
slide-25
SLIDE 25
slide-26
SLIDE 26

Design Guidelines

  • Craft [good/pretty/usable/stable] URIs
  • Map domain actions to HTTP methods (CRUD)
  • Use the proper HTTP Status Codes
  • Document serialized objects as HTTP bodies
  • Use HTTP headers responsibly
  • Describe edge cases (async, errors, authN/Z)
slide-27
SLIDE 27
slide-28
SLIDE 28
slide-29
SLIDE 29
slide-30
SLIDE 30
slide-31
SLIDE 31
slide-32
SLIDE 32

But there's a problem here...

slide-33
SLIDE 33

Those are not design guidelines..

slide-34
SLIDE 34

They are implementation guidelines!

slide-35
SLIDE 35
slide-36
SLIDE 36

Ok, so what is a design methodology, then?

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

Here's a simple seven-step procedure...

slide-40
SLIDE 40

Yep, seven steps.

slide-41
SLIDE 41

Let's design a Maze game API

slide-42
SLIDE 42
slide-43
SLIDE 43
  • 1. List the Semantic Descriptors
slide-44
SLIDE 44
  • 1. List the Semantic Descriptors

(the what?)

slide-45
SLIDE 45
  • 1. List the Semantic Descriptors

(the what?) You know, the stuff!

slide-46
SLIDE 46

Ubiquitous Language

Ubiquitous Language is the term Eric Evans uses in Domain Driven Design for the practice of building up a common, rigorous language between developers and users. This language should be based on the Domain Model used in the software - hence the need for it to be rigorous, since software doesn't cope well with ambiguity.

  • - Martin Fowler, 2006
slide-47
SLIDE 47

Ubiquitous Language

Ubiquitous Language is the term Eric Evans uses in Domain Driven Design for the practice of building up a common, rigorous language between developers and users. This language should be based on the Domain Model used in the software - hence the need for it to be rigorous, since software doesn't cope well with ambiguity.

  • - Martin Fowler, 2006
slide-48
SLIDE 48
  • 1. List the Semantic Descriptors
  • A maze
  • A maze cell
  • A switch
  • Switch position ("up" or "down")
  • The title of a maze cell
  • A doorway connecting to cells
  • An exit from the maze
  • A list of mazes
slide-49
SLIDE 49
slide-50
SLIDE 50
  • 2. Draw a State Diagram
slide-51
SLIDE 51

State Charts

State Charts are compact and expressive – small diagrams can express complex behavior – as well as compositional and modular.

  • - David Harel, 2002
slide-52
SLIDE 52

State Charts

State Charts are compact and expressive – small diagrams can express complex behavior – as well as compositional and modular.

  • - David Harel, 2002
slide-53
SLIDE 53
slide-54
SLIDE 54
  • 3. Reconcile Names
slide-55
SLIDE 55
  • 3. Reconcile Names
  • IANA Link Relation Values
  • schema.org
  • microformats
  • Dublin Core
  • Activity Streams
slide-56
SLIDE 56
  • 3. Reconcile Names
  • maze
  • start
  • current
  • exit
  • north, south, east, west
  • switch
  • flip
slide-57
SLIDE 57
  • 3. Reconcile Names
  • maze
  • start (IANA)
  • current (IANA)
  • exit
  • north, south, east, west
  • switch
  • flip
slide-58
SLIDE 58
  • 3. Reconcile Names
  • maze
  • start (IANA)
  • current (IANA)
  • exit (microformats)
  • north, south, east, west (microformats)
  • switch
  • flip
slide-59
SLIDE 59
  • 3. Reconcile Names
  • maze
  • start (IANA)
  • current (IANA)
  • exit (microformats)
  • north, south, east, west (microformats)
  • switch
  • flip edit (IANA)
slide-60
SLIDE 60
  • 3. Reconcile Names
  • http://mamund.com/rels/maze (RFC5988)
  • start (IANA)
  • current (IANA)
  • exit (microformats)
  • north, south, east, west (microformats)
  • http://mamund.com.rels/switch (RFC5988)
  • flip edit (IANA)
slide-61
SLIDE 61
  • 3. Reconcile Names
  • IANA
  • edit
  • start
  • current
  • microformats
  • exit
  • north, south, east, west
  • RFC5988
  • http://mamund.com/rels/switch
  • http://mamund.com/rels/maze
slide-62
SLIDE 62
slide-63
SLIDE 63

OK, that was the design part...

slide-64
SLIDE 64

But I still need to implement it, right?

slide-65
SLIDE 65
  • 4. Choose a Media Type
slide-66
SLIDE 66
  • 4. Choose a Media Type
  • Use application/json, application/xml
  • Collection type: Atom, OData, Collection+JSON
  • Free-form: HTML, Siren, HAL, JSON-LD
  • Invent your own semantic type
slide-67
SLIDE 67

Message-Passing

The big idea is "messaging" - that is what the kernal of Smalltalk/Squeak is all about The key in making great and grow-able systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be.

  • - Alan Kay, 1998
slide-68
SLIDE 68

Message-Passing

The big idea is "messaging" - that is what the kernal of Smalltalk/Squeak is all about The key in making great and grow-able systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be.

  • - Alan Kay, 1998
slide-69
SLIDE 69
  • 4. Choose a Media Type
  • Use application/json, application/xml
  • Collection type: Atom, OData, Collection+JSON
  • Free-form: HTML, Siren, HAL, JSON-LD
  • Invent your own semantic type
slide-70
SLIDE 70
  • 4. Choose a Media Type
  • Use application/json, application/xml
  • Collection type: Atom, OData, Collection+JSON
  • Free-form: HTML, Siren, HAL, JSON-LD
  • Invent your own semantic type
slide-71
SLIDE 71
  • 4. Choose a Media Type
  • Use application/json, application/xml
  • Collection type: Atom, OData, Collection+JSON
  • Free-form: HTML, Siren, HAL, JSON-LD
  • Invent your own semantic type
slide-72
SLIDE 72
  • 4. Choose a Media Type
  • Use application/json, application/xml
  • Collection type: Atom, OData, Collection+JSON
  • Free-form: HTML, Siren, HAL, JSON-LD
  • Invent your own semantic type
slide-73
SLIDE 73
  • 4. Choose a Media Type
  • Use application/json, application/xml
  • Collection type: Atom, OData, Collection+JSON
  • Free-form: HTML, Siren, HAL, JSON-LD
  • Invent your own semantic type
slide-74
SLIDE 74
slide-75
SLIDE 75
slide-76
SLIDE 76

Collection+JSON

slide-77
SLIDE 77

UBER+xml

slide-78
SLIDE 78

MAZE+xml

slide-79
SLIDE 79
  • 5. Write a Profile
slide-80
SLIDE 80

Profiles RFC

A profile allows clients to learn about additional semantics that are associated with the resource.

  • - Erik Wilde, 2013
slide-81
SLIDE 81

Profiles RFC

A profile allows clients to learn about additional semantics that are associated with the resource.

  • - Erik Wilde, 2013
slide-82
SLIDE 82
slide-83
SLIDE 83
slide-84
SLIDE 84
  • 6. Implementation
slide-85
SLIDE 85
  • 6. Implementation

ta-da!

slide-86
SLIDE 86
slide-87
SLIDE 87
slide-88
SLIDE 88
slide-89
SLIDE 89
slide-90
SLIDE 90
slide-91
SLIDE 91
slide-92
SLIDE 92

And now we have running code!

slide-93
SLIDE 93

Wait, what's step seven?

slide-94
SLIDE 94
  • 7. Publication
slide-95
SLIDE 95
  • 7. Publication
  • Publish your "billboard" URL
  • Publish your profile
  • Register new rel values and/or media types
  • Publish the documentation
  • Consider "well-known" URIs
slide-96
SLIDE 96

Now, you're done!

slide-97
SLIDE 97

Seven Simple Steps

  • 1. List the Semantic Descriptors
  • 2. Draw a State Diagram
  • 3. Reconcile Names
  • 4. Write a Profile
  • 5. Select a Media Type
  • 6. Implementation
  • 7. Publication
slide-98
SLIDE 98

Some Final Advice

slide-99
SLIDE 99

Resources are an implementation detail

slide-100
SLIDE 100
slide-101
SLIDE 101

Don't fall into the collection trap

slide-102
SLIDE 102
slide-103
SLIDE 103

Don't start with the representation format

slide-104
SLIDE 104
slide-105
SLIDE 105

URL design doesn't matter

slide-106
SLIDE 106
slide-107
SLIDE 107

Standard names are probably better than yours.

slide-108
SLIDE 108
slide-109
SLIDE 109

Don't keep all the hypermedia in one place

slide-110
SLIDE 110
slide-111
SLIDE 111
slide-112
SLIDE 112

Some Final Advice

  • Resources are implementation details
  • Don't fall into the collection trap
  • Don't start w/ the representation format
  • URL design doesn't matter
  • Standard names are probably better than

yours

  • Don't keep all the hypermedia in one place
slide-113
SLIDE 113

In Conclusion...

slide-114
SLIDE 114
slide-115
SLIDE 115
slide-116
SLIDE 116
slide-117
SLIDE 117
slide-118
SLIDE 118
slide-119
SLIDE 119

In Conclusion...

  • Don't confuse implementation w/ design
  • Design is the hard part (high value)
  • Implementation is the easy part (high speed)
  • Avoid common design mistakes
  • Go out and make lots of APIs!
slide-120
SLIDE 120

API Design Methodology

Mike Amundsen API Academy / CA @mamund