At some point, we all need to design and implement APIs for the Web. What makes Web APIs different than typical component APIs? How can you leverage the power of the Internet when creating your Web API? What characteristics to many "great" Web APIs share? Is there a consistent process you can use to make sure you design a Web API that best fits your needs both now and in the future? In this session Mike Amundsen describes a clear methodology for designing Web APIs (based on the book "RESTful Web APIs" by Richardson and Amundsen) that allows you to map key aspects of your business into a usable, scalable, and flexible interface that will reach your goals while creating a compelling API for both server and client developers. Whether you are looking to implement a private, partner, or public API, these principles will help you focus on the right metrics and design goals to create a successful API.

1. API Design Methodology
Mike Amundsen,
CA / Layer7
@mamund

2. Introduction

12. Actually, we have a
methodology already...

13. Design Guidelines
● Craft [good/pretty/usable/stable] URIs

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

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

19. 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

21. 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

23. 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)

29. But there's a problem here...

30. Those are not design guidelines..

31. They are implementation guidelines!

33. Ok, so what is a design
methodology, then?

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

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

38. Let's design a Maze game API

40. 1. List the Semantic Descriptors

41. 1. List the Semantic Descriptors
(the what?)

42. 1. List the Semantic Descriptors
(the what?)
You know, the stuff!

43. 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

45. 2. Draw a State Diagram

47. 3. Reconcile Names

48. 3. Reconcile Names
● IANA Link Relation Values
● schema.org
● microformats
● Dublin Core
● Activity Streams

49. 3. Reconcile Names
● maze
● start
● current
● exit
● north, south, east, west
● switch
● flip

50. 3. Reconcile Names
● maze
● start (IANA)
● current (IANA)
● exit
● north, south, east, west
● switch
● flip

51. 3. Reconcile Names
● maze
● start (IANA)
● current (IANA)
● exit (microformats)
● north, south, east, west (microformats)
● switch
● flip

52. 3. Reconcile Names
● maze
● start (IANA)
● current (IANA)
● exit (microformats)
● north, south, east, west (microformats)
● switch
● flip edit (IANA)

53. 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)

54. 3. Reconcile Names
● IANA
o edit
o start
o current
● microformats
o exit
o north, south, east, west
● RFC5988
o http://mamund.com/rels/switch
o http://mamund.com/rels/maze

56. OK, that was the design part...

57. But I still need to implement it,
right?

58. 4. Choose a Media Type

59. 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

60. 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

61. 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

62. 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

63. 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

66. Collection+JSON

67. UBER+xml

68. MAZE+xml

69. 5. Write a Profile

72. 6. Implementation

73. 6. Implementation
ta-da!

80. And now we have running code!

81. Wait, what's step seven?

82. 7. Publication

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

84. Now, you're done!

85. 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

86. Some Final Advice

87. Resources are an
implementation detail

89. Don't fall into the collection trap

91. Don't start with the
representation format

93. URL design doesn't matter

95. Standard names are probably better
than yours.

97. Don't keep all the hypermedia
in one place

100. 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

101. In Conclusion...

107. 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!

108. API Design Methodology
Mike Amundsen,
CA / Layer7
@mamund