@mamund ca / layer7 mike amundsen,some final advice resources are implementation details don't...

API Design MethodologyMike Amundsen,

CA / Layer7@mamund

Introduction

Actually, we have a methodology already...

Design Guidelines

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

Design Guidelines

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

Design Guidelines

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

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

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

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)

But there's a problem here...

Those are not design guidelines..

They are implementation guidelines!

Ok, so what is a design methodology, then?

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

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

Let's design a Maze game API

1. List the Semantic Descriptors

1. List the Semantic Descriptors(the what?)

1. List the Semantic Descriptors(the what?)

You know, the stuff!

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

2. Draw a State Diagram

3. Reconcile Names

3. Reconcile Names

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

3. Reconcile Names

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

3. Reconcile Names

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

3. Reconcile Names

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

3. Reconcile Names

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

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)

3. Reconcile Names● IANA

○ edit○ start ○ current

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

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

OK, that was the design part...

But I still need to implement it, right?

4. Choose a Media Type

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

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

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

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

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

5. Write a Profile

6. Implementation

6. Implementation

ta-da!

And now we have running code!

Wait, what's step seven?

7. Publication

7. Publication

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

Now, you're done!

Seven Simple Steps

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

Some Final Advice

Resources are an implementation detail

Don't fall into the collection trap

Don't start with the representation format

URL design doesn't matter

Standard names are probably better than yours.

Don't keep all the hypermedia in one place

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

In Conclusion...

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!

API Design MethodologyMike Amundsen,

CA / Layer7@mamund