111
API Design Methodology Mike Amundsen, CA / Layer7 @mamund

@mamund CA / Layer7 Mike Amundsen,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

  • Upload
    others

  • View
    1

  • Download
    0

Embed Size (px)

Citation preview

Page 1: @mamund CA / Layer7 Mike Amundsen,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

API Design MethodologyMike Amundsen,

CA / Layer7@mamund

Page 2: @mamund CA / Layer7 Mike Amundsen,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

Introduction

Page 3: @mamund CA / Layer7 Mike Amundsen,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
Page 4: @mamund CA / Layer7 Mike Amundsen,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
Page 5: @mamund CA / Layer7 Mike Amundsen,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
Page 6: @mamund CA / Layer7 Mike Amundsen,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
Page 7: @mamund CA / Layer7 Mike Amundsen,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
Page 8: @mamund CA / Layer7 Mike Amundsen,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
Page 9: @mamund CA / Layer7 Mike Amundsen,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
Page 10: @mamund CA / Layer7 Mike Amundsen,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
Page 11: @mamund CA / Layer7 Mike Amundsen,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
Page 12: @mamund CA / Layer7 Mike Amundsen,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
Page 13: @mamund CA / Layer7 Mike Amundsen,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
Page 14: @mamund CA / Layer7 Mike Amundsen,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
Page 15: @mamund CA / Layer7 Mike Amundsen,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
Page 16: @mamund CA / Layer7 Mike Amundsen,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
Page 17: @mamund CA / Layer7 Mike Amundsen,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
Page 18: @mamund CA / Layer7 Mike Amundsen,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

Actually, we have a methodology already...

Page 19: @mamund CA / Layer7 Mike Amundsen,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

Design Guidelines

● Craft [good/pretty/usable/stable] URIs

Page 20: @mamund CA / Layer7 Mike Amundsen,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
Page 21: @mamund CA / Layer7 Mike Amundsen,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

Design Guidelines

● Craft [good/pretty/usable/stable] URIs● Map domain actions to HTTP methods (CRUD)

Page 22: @mamund CA / Layer7 Mike Amundsen,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
Page 23: @mamund CA / Layer7 Mike Amundsen,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

Design Guidelines

● Craft [good/pretty/usable/stable] URIs● Map domain actions to HTTP methods (CRUD)● Use the proper HTTP Status Codes

Page 24: @mamund CA / Layer7 Mike Amundsen,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
Page 25: @mamund CA / Layer7 Mike Amundsen,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

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

Page 26: @mamund CA / Layer7 Mike Amundsen,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
Page 27: @mamund CA / Layer7 Mike Amundsen,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

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

Page 28: @mamund CA / Layer7 Mike Amundsen,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
Page 29: @mamund CA / Layer7 Mike Amundsen,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

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)

Page 30: @mamund CA / Layer7 Mike Amundsen,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
Page 31: @mamund CA / Layer7 Mike Amundsen,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
Page 32: @mamund CA / Layer7 Mike Amundsen,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
Page 33: @mamund CA / Layer7 Mike Amundsen,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
Page 34: @mamund CA / Layer7 Mike Amundsen,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
Page 35: @mamund CA / Layer7 Mike Amundsen,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

But there's a problem here...

Page 36: @mamund CA / Layer7 Mike Amundsen,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

Those are not design guidelines..

Page 37: @mamund CA / Layer7 Mike Amundsen,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

They are implementation guidelines!

Page 38: @mamund CA / Layer7 Mike Amundsen,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
Page 39: @mamund CA / Layer7 Mike Amundsen,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

Ok, so what is a design methodology, then?

Page 40: @mamund CA / Layer7 Mike Amundsen,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
Page 41: @mamund CA / Layer7 Mike Amundsen,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
Page 42: @mamund CA / Layer7 Mike Amundsen,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

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

Page 43: @mamund CA / Layer7 Mike Amundsen,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

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

Page 44: @mamund CA / Layer7 Mike Amundsen,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

Let's design a Maze game API

Page 45: @mamund CA / Layer7 Mike Amundsen,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
Page 46: @mamund CA / Layer7 Mike Amundsen,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

1. List the Semantic Descriptors

Page 47: @mamund CA / Layer7 Mike Amundsen,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

1. List the Semantic Descriptors(the what?)

Page 48: @mamund CA / Layer7 Mike Amundsen,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

1. List the Semantic Descriptors(the what?)

You know, the stuff!

Page 49: @mamund CA / Layer7 Mike Amundsen,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

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

Page 50: @mamund CA / Layer7 Mike Amundsen,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
Page 51: @mamund CA / Layer7 Mike Amundsen,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

2. Draw a State Diagram

Page 52: @mamund CA / Layer7 Mike Amundsen,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
Page 53: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names

Page 54: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names

● IANA Link Relation Values● schema.org● microformats● Dublin Core● Activity Streams

Page 55: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names

● maze● start● current● exit● north, south, east, west● switch● flip

Page 56: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names

● maze● start (IANA)● current (IANA)● exit● north, south, east, west● switch● flip

Page 57: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names

● maze● start (IANA)● current (IANA)● exit (microformats)● north, south, east, west (microformats)● switch● flip

Page 58: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names

● maze● start (IANA)● current (IANA)● exit (microformats)● north, south, east, west (microformats)● switch● flip edit (IANA)

Page 59: @mamund CA / Layer7 Mike Amundsen,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

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)

Page 60: @mamund CA / Layer7 Mike Amundsen,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

3. Reconcile Names● IANA

○ edit○ start ○ current

● microformats○ exit○ north, south, east, west

● RFC5988○ http://mamund.com/rels/switch ○ http://mamund.com/rels/maze

Page 61: @mamund CA / Layer7 Mike Amundsen,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
Page 62: @mamund CA / Layer7 Mike Amundsen,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

OK, that was the design part...

Page 63: @mamund CA / Layer7 Mike Amundsen,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

But I still need to implement it, right?

Page 64: @mamund CA / Layer7 Mike Amundsen,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

4. Choose a Media Type

Page 65: @mamund CA / Layer7 Mike Amundsen,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

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

Page 66: @mamund CA / Layer7 Mike Amundsen,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

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

Page 67: @mamund CA / Layer7 Mike Amundsen,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

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

Page 68: @mamund CA / Layer7 Mike Amundsen,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

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

Page 69: @mamund CA / Layer7 Mike Amundsen,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

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

Page 70: @mamund CA / Layer7 Mike Amundsen,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
Page 71: @mamund CA / Layer7 Mike Amundsen,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
Page 72: @mamund CA / Layer7 Mike Amundsen,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

5. Write a Profile

Page 73: @mamund CA / Layer7 Mike Amundsen,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
Page 74: @mamund CA / Layer7 Mike Amundsen,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
Page 75: @mamund CA / Layer7 Mike Amundsen,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

6. Implementation

Page 76: @mamund CA / Layer7 Mike Amundsen,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

6. Implementation

ta-da!

Page 77: @mamund CA / Layer7 Mike Amundsen,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
Page 78: @mamund CA / Layer7 Mike Amundsen,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
Page 79: @mamund CA / Layer7 Mike Amundsen,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
Page 80: @mamund CA / Layer7 Mike Amundsen,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
Page 81: @mamund CA / Layer7 Mike Amundsen,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
Page 82: @mamund CA / Layer7 Mike Amundsen,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
Page 83: @mamund CA / Layer7 Mike Amundsen,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

And now we have running code!

Page 84: @mamund CA / Layer7 Mike Amundsen,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

Wait, what's step seven?

Page 85: @mamund CA / Layer7 Mike Amundsen,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

7. Publication

Page 86: @mamund CA / Layer7 Mike Amundsen,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

7. Publication

● Publish your "billboard" URL● Publish your profile● Register new rel values and/or media types● Publish the documentation● Consider "well-known" URIs

Page 87: @mamund CA / Layer7 Mike Amundsen,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

Now, you're done!

Page 88: @mamund CA / Layer7 Mike Amundsen,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

Seven Simple Steps

1. List the Semantic Descriptors2. Draw a State Diagram3. Reconcile Names4. Write a Profile5. Select a Media Type6. Implementation7. Publication

Page 89: @mamund CA / Layer7 Mike Amundsen,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

Some Final Advice

Page 90: @mamund CA / Layer7 Mike Amundsen,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

Resources are an implementation detail

Page 91: @mamund CA / Layer7 Mike Amundsen,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
Page 92: @mamund CA / Layer7 Mike Amundsen,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

Don't fall into the collection trap

Page 93: @mamund CA / Layer7 Mike Amundsen,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
Page 94: @mamund CA / Layer7 Mike Amundsen,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

Don't start with the representation format

Page 95: @mamund CA / Layer7 Mike Amundsen,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
Page 96: @mamund CA / Layer7 Mike Amundsen,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

URL design doesn't matter

Page 97: @mamund CA / Layer7 Mike Amundsen,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
Page 98: @mamund CA / Layer7 Mike Amundsen,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

Standard names are probably better than yours.

Page 99: @mamund CA / Layer7 Mike Amundsen,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
Page 100: @mamund CA / Layer7 Mike Amundsen,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

Don't keep all the hypermedia in one place

Page 101: @mamund CA / Layer7 Mike Amundsen,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
Page 102: @mamund CA / Layer7 Mike Amundsen,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
Page 103: @mamund CA / Layer7 Mike Amundsen,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

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

Page 104: @mamund CA / Layer7 Mike Amundsen,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

In Conclusion...

Page 105: @mamund CA / Layer7 Mike Amundsen,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
Page 106: @mamund CA / Layer7 Mike Amundsen,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
Page 107: @mamund CA / Layer7 Mike Amundsen,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
Page 108: @mamund CA / Layer7 Mike Amundsen,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
Page 109: @mamund CA / Layer7 Mike Amundsen,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
Page 110: @mamund CA / Layer7 Mike Amundsen,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

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!

Page 111: @mamund CA / Layer7 Mike Amundsen,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

API Design MethodologyMike Amundsen,

CA / Layer7@mamund