We Need to Talk About Docs

Presentation given at API Days AU 2016.

Transcript

1. nik wakelin
2. @nikz
3. we need to TALK about DOCS
6. gelato.io
8. we could be doing so. much. better
11. avoid
12. avoid assume
13. avoid assume abandon
14. avoid assume abandon abbr.
15. AVOID
16. the only “self-documenting” interface
17. HATEOAS
18. HATEOAS
19. “intern! heel!”
20. cherry on top
21. AVOID
22. AVOID EMBRACE!
23. require great docs great effort
24. HATEOAS why the nik?
25. making life easy for yourself at the expense of your developers!
26. map? don’t your developers deserve a
27. 0 ∞ N(API requests) humans computers!
28. complexity
29. “guided” client make HTTP request deal with response
30. “D.E.Y.” client make HTTP request follow links caching? handle HTTP 410 deal with response & etc.. & etc…
31. season with metadata pagination, webhooks…
33. ASSUME
34. devs code! ===
35. swagger-ui time for a beer!
36. ASSUME
37. ASSUME UNDERSTAND
38. your devs you your API client code
39. your devs you your API client code '!
40. lost translation in
42. Swagger / OAI, API Blueprint, RAML…
43. Swagger / OAI, API Blueprint, RAML… (a good start)
44. what is important, but don’t forget why?
45. speak human! speaking to humans?
46. better together
47. guides are just recipes
48. always be testing!
50. ABANDON
51. last updated never
52. support “forum”
54. ABANDON
55. ABANDON MAINTAIN
58. your API is just like any other feature
59. avoid the big bang!
62. monitor
64. ABBR.
65. P D F retty ead ormat
66. list of endpoints how to authenticate 200 OK 201 CREATED
67. list of endpoints how to authenticate 200 OK 201 CREATED 299 TIME FOR A BEER?
69. ABBR.
70. ABBR. EXPAND
71. what delivery does your say?
73. developer.yourapp.com
76. who is using my API?
77. @yourapi
78. slack.com
79. gitter.im
80. talk!
81. xero.com/add-ons
83. done? when am I API Explorer, Credential Management, Dev Registration, Account Dashboard, (good!) search, …
84. (never)
87. EMBRACE effort
88. help your developers UNDERSTAND
89. keep up the good work! MAINTAIN
90. do more for your devs! EXPAND
91. go out there and CREATE amazing EXPERIENCES
92. gelato.io
93. getgalileo.io
94. getkong.org
95. thanks!
96. nik wakelin
97. @nikz
98. nik@mashape.com
99. thanks! Pipes, Isado (https://www.flickr.com/photos/isadocafe/ 3268348703) Tui Bird, Cat Burton (https://www.flickr.com/photos/ catburton/16023893948/) Mailboxes, Olga Caprotti (https://www.flickr.com/photos/ __olga__/2822660113/) Delivery Man, Chris Bird (https://www.flickr.com/photos/ 118292762@N02/15475876255) Tools, Paul Downey (https://www.flickr.com/photos/psd/ 5298483) Kittens, abcrumley (https://www.flickr.com/photos/ crumley/160490011/) M82 Galaxy, Stuart Rankin (https://www.flickr.com/ photos/24354425@N03/12808714524/) Wrong Way, David Goehring (https://www.flickr.com/ photos/carbonnyc/7777982086) Neuschwanstein, Markus Jaschke (https://www.flickr.com/ photos/schomy/22547613404) Tumbleweed, USFS Mountain-Prairie (https:// www.flickr.com/photos/usfwsmtnprairie/13981953730/)
100. thanks! Tokyo Signs from Anton G (https://www.flickr.com/ photos/s7stem/2645936875/) Secret Bunker, Marcomo (https://www.flickr.com/ photos/marcmos/3674715600) Baby with Bottle, David Precious (https:// www.flickr.com/photos/bigpresh/10176739514/) Weightlifting, Singapore 2010 (https:// www.flickr.com/photos/singapore2010/4897930037/) Coffee from Linh Nguyen (https://www.flickr.com/ photos/lng0004/15541408139/) Gimme a Boost, Brittney Bush Bollay (https:// www.flickr.com/photos/tzofia/843491313) Sundae, Thomas Hawk (https://www.flickr.com/ photos/thomashawk/2500262938) Tourist Reading Map, Pedro Ribeiro Simões (https:// www.flickr.com/photos/pedrosimoes7/8150135751/in/) Indian Spices, Sara Marlowe (https:// www.flickr.com/photos/saramarlowe/8170948596/) OK Diner, Andrew Bartram (https://www.flickr.com/ photos/warboyssnapper/6780082962)
101. thanks! Run Down House, Henning Klokkeråsen (https:// www.flickr.com/photos/photohenning/20879839580/) Play House, Paul Sableman (https://www.flickr.com/ photos/pasa/16410623154) Straya from Jes (https://www.flickr.com/photos/ mugley/307473865/) Red Bull in, Code Out from Tahir Hashmi (https:// www.flickr.com/photos/code_martial/2501920341/) Oscilliscope, Eli Brody, (https://www.flickr.com/ photos/coldphage/3535410747) Exams, Cushing Memorial Library (https:// www.flickr.com/photos/cushinglibrary/3607496812) Why?, Katy Sayer (https://www.flickr.com/photos/ ksayer/5614813544/) Complexity, Mark Skipper (https://www.flickr.com/ photos/bitterjug/7670055210/)
102. ?