Human First API Design

Human first API Design: APIs, SOAP, Hypermedia, REST - we get so dogmatic about it all! But on many occasions we should be putting humans first in our API design. This presentation explores the history of APIs and how and why you should design them for humans first.

Transcript

1. Human First API Design Monday, October 6, 14
2. @motdotla Monday, October 6, 14
3. What is an API? Monday, October 6, 14
4. Application Programming Interface Generically Monday, October 6, 14
5. A set of programming instructions for accessing a Web-based software application. Colloquially Monday, October 6, 14
6. https://api.twitter.com/ 1.1/search/tweets.json? q=USC In Practice Monday, October 6, 14
7. History of APIs Monday, October 6, 14
8. 1990s Monday, October 6, 14
9. In the beginning, there was not the web. It’s the year 1990 and it has not yet come about. Sir Tim Berners-Lee has not yet given it to us. Monday, October 6, 14
10. By Christmas 1990, Sir Tim Berners-Lee had given us HTTP, HTML, and the first web browser (named WorldWideWeb). Monday, October 6, 14
11. First API! * GET request and HTML response. * Human friendly. Monday, October 6, 14
12. Browser Wars Monday, October 6, 14
13. WorldWideWeb Mosaic Netscape Internet Explorer Monday, October 6, 14
14. More than HTML. Images, JavaScript, CSS, and more. Monday, October 6, 14
15. Roaring 2000 Monday, October 6, 14
16. Startup empires are built. Ebay, PayPal, Salesforce, and many other giants come out of the late 1990s and the year 2000. Monday, October 6, 14
17. Depression Monday, October 6, 14
18. The bubble bursts. Enter the API. Monday, October 6, 14
19. BizDev 2.0 February 7th, 2000. Salesforce. November 20th, 2000. Ebay. Monday, October 6, 14
20. APIs are wild. No accepted rules. Monday, October 6, 14
21. SOAP Monday, October 6, 14
22. SOAP rises to the forefront as a standard - by Microsoft and the W3C. Monday, October 6, 14
23. UNREST Monday, October 6, 14
24. The rule of SOAP causes problems. It leads to an inflation of code. The cost to fuel one’s application becomes prohibitive. Bugs pile up, todos pile up in long lines. There just isn’t enough resources to offset the problems SOAP introduces. Monday, October 6, 14
25. Incidentally, there are still people living in those SOAP days. I weep for them. Monday, October 6, 14
26. REST Monday, October 6, 14
27. Roy Fielding Monday, October 6, 14
28. Dissertation: “Architectural Styles and the Design of Network-based Software Architectures”. Monday, October 6, 14
29. Removes the ‘UN’ from ‘UNREST’ Monday, October 6, 14
30. Renaissance Monday, October 6, 14
31. Creativity unleashed. Developers create APIs quickly, and mashups from there. Monday, October 6, 14
32. 2005. Programmable Web. Monday, October 6, 14
33. 2006. Ruby on Rails. Popularizes REST. Monday, October 6, 14
34. API first companies like Twilio & SendGrid thrive. They generally follow REST principles with a tinge of pragmatism. This leads to useful and beautiful things. Monday, October 6, 14
35. The developer is loved during this time. The focus is the developer - not machines. Monday, October 6, 14
36. Progress Monday, October 6, 14
37. New empires are built. But slowly REST loses it’s focus on the developer - on the human. Monday, October 6, 14
38. REST becomes increasingly cold and complex. Monday, October 6, 14
39. Use the correct verb. Monday, October 6, 14
40. New verbs are introduced like PATCH and HEAD. Monday, October 6, 14
41. Complex OAuth authentication becomes the accepted dogma for authenticating an API. Monday, October 6, 14
42. Strict status code usage. Monday, October 6, 14
43. Settings in the headers. Monday, October 6, 14
44. Hypermedia is introduced - adding more complexity. Monday, October 6, 14
45. People preach the REST way and scorn alternative thinking. Monday, October 6, 14
46. The focus is shifting to the machine, and humans are being left out in the cold. Monday, October 6, 14
47. A Heretical Approach: Human First API Design Monday, October 6, 14
48. Guiding Beliefs Monday, October 6, 14
49. Easy as a URL. Monday, October 6, 14
50. https://carte-api.herokuapp.com/api/v0/accounts/ create.json?email=[email]&api_key=[api_key] Monday, October 6, 14
51. Authorization key in the URL. Monday, October 6, 14
52. /accounts/create.json? api_key=[api_key]&email=[ email] Monday, October 6, 14
53. Verb (action) in the URL. Monday, October 6, 14
54. /accounts/create.json? api_key=[api_key]&email=[ email] Monday, October 6, 14
55. Allow for POST body instead of URL. Monday, October 6, 14
56. curl -X POST \ /accounts/create.json \ -d“api_key=[api_key]” \ -d “email=[email] Monday, October 6, 14
57. Any verb. Monday, October 6, 14
58. GET POST *any Monday, October 6, 14
59. There are three things a developer wants to know. Did it work, did I mess up, or did the service mess up. Start with those three - 200, 400, and 500. Get more granular as necessary. Monday, October 6, 14
60. 200 400 500 Monday, October 6, 14
61. Output should be JSON and probably recommended format as json:api. Monday, October 6, 14
62. Monday, October 6, 14
63. Human First Examples Monday, October 6, 14
64. Monday, October 6, 14
65. https://api.sendgrid.com/api/mail.send.json? api_user=[api_user]& api_key=[api_key]& to=[to]& from=[from]& subject=[subject]& text=[text] Monday, October 6, 14
66. Monday, October 6, 14
67. Monday, October 6, 14
68. https://api.digitalocean.com/v1/droplets/new? client_id=[client_id]& api_key=[api_key]& name=[droplet_name]& size_id=[size_id]& image_id=[image_id]& region_id=[region_id]&ssh_key_ids= [ssh_key_id1],[ssh_key_id2] Monday, October 6, 14
69. Monday, October 6, 14
70. Next time you build an API consider if you should design it for humans first. Monday, October 6, 14
71. Resources • http://jsonapi.org/ • http://history.apievangelist.com/ • http://money.howstuffworks.com/business-communications/how-to-leverage- an-api-for-conferencing1.htm • https://sendgrid.com • https://digitalocean.com Monday, October 6, 14
72. Thanks Monday, October 6, 14