How to create a Web API no one wants to use

5,223 views
4,656 views

Published on

Later this year, Netflix will be closing their public APIs. Twitter and Google have already restricted their APIs. Despite prominent tech-companies making drastic changes to their APIs, the number of APIs keeps growing steadily. Suddenly, everyone has an API. Your car has one, Chuck Norris has one, and worst of all, tech-companies with no focus on quality whatsoever has one. And who are using these APIs? Most likely, no one.

This presentation will take you through the pitfalls of creating an API. From a developers perspective, what mistakes will result in no one wanting to use your API?

Live examples:
Download the Postman Chrome extension and import the following collections:
https://www.getpostman.com/collections/ede2ced9d83ddf66ba93
https://www.getpostman.com/collections/20c0047a17211caa631f
https://www.getpostman.com/collections/23bfb218456adb5c0a63

Published in: Engineering, Internet, Technology
0 Comments
70 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
5,223
On SlideShare
0
From Embeds
0
Number of Embeds
292
Actions
Shares
0
Downloads
124
Comments
0
Likes
70
Embeds 0
No embeds

No notes for slide

How to create a Web API no one wants to use

  1. HOW TO CREATE A WEB API NO ONE WANTS TO USE By /Karoline Klever @karolikl
  2. THE GAME NO ONE WANTS TO USE MY API I have never created a public web API
  3. TAKING A LOOK at the world of Web APIs...
  4. YOUR CAR HAS ONE
  5. CHUCK NORRIS HAS ONE
  6. YOUR DOG HAS ONE
  7. THE NUMBER OF WEB APIS is increasing fast
  8. 1995 "Why do we need a website?"
  9. 2000 "Of course we have a website!"
  10. 2005 "Why do we need an API?"
  11. 2010 "Of course we have an API!"
  12. URI DESIGN Badly named and inconsistent URIs that violate the Principle of Least Astonishment will make your web API just as disappointing as the movie "Mega Shark vs Giant Octopus"
  13. PRINCIPLE OF LEAST ASTONISHMENT "[...] a programmer should try to think of the behavior that will least surprise someone who uses the program, rather than that behavior that is natural from knowing the inner workings of the program."
  14. PROBLEM #1 INCONSISTENT URI STRUCTURE We cannot guess the URI of an endpoint based on our experience with the other endpoints.
  15. PROBLEM #2 URIS ARE NOT HACKABLE /all_links_for_city_of/chicago/il.json /all_links_for_city_of/chicago/il.json /all_links_for_city_of/chicago/il.json
  16. PROBLEM #3 LINK TYPES /all_links_for_city_of/chicago/il.json /all_links_for_county_of/cook%20county/i /primary_links_for_city_of/chicago/il.js /primary_links_for_county_of/cook%20coun
  17. POSSIBLE SOLUTION (ONE OF MANY) /links /links/il /links/il/cook%20county /links/il/cook%20county/chicago /links/il/cook%20county/chicago? type=primary
  18. THE GAME NO ONE WANTS TO USE MY API Inconsistency Violation
  19. HTTP VERBS Why do we need anything other than GET?
  20. THE MOST COMMONLY USED GET PUT POST DELETE
  21. SAFE METHODS "... the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered "safe"."
  22. ARE THEY SAFE? GET: Yes PUT: No POST: No DELETE: No
  23. IDEMPOTENT METHODS Methods we can issue the same request against as many times as we want without changing the result.
  24. ARE THEY IDEMPOTENT? GET: Yes PUT: Yes POST: No DELETE: Yes
  25. GET CLIMATE GET/vehicles/{id}/command/climate_state { "inside_temp":17.0, "outside_temp":9.5, "driver_temp_setting":22.6, "passenger_temp_setting":22.6, "is_auto_conditioning_on":false, "is_front_defroster_on":null, "is_rear_defroster_on":false, "fan_status":0 }
  26. OPEN SUNROOF GET/vehicles/{id}/command/sun_roof_control?state=open
  27. POSSIBLE SOLUTION GET/vehicles/{id}/command/sun_roof_control { "state":"open" } PUT/vehicles/{id}/command/sun_roof_control?state=open { "result":true }
  28. THE OTHER VERBS? GET Returns the state of the sun roof (open/closed) PUT Open/close the sunroof POST Not supported, cannot create new sun roof DELETE Not supported, cannot delete sun roof
  29. THE GAME NO ONE WANTS TO USE MY API Only GET Wrong verb
  30. HTTP STATUS CODES Everyone just loves an "error in disguise"
  31. PROBLEM #1 DISGUISING YOUR ERRORS Invalid requests return with a 200 OK status code, giving the impression that the request was successful.
  32. PROBLEM #2 DISPLAYING YOUR INTERNALS Including a detailed error report or stacktrace makes your Web API vulnerable to attack
  33. THE BASICS 200 OK Awesome! 400 Bad Request The user of the API made a mistake 500 Internal Server Error The creator of the API made a mistake
  34. POSSIBLE SOLUTION GEThttp://api.worldbank.org/countries/a?format=json 400BadRequest GEThttp://api.worldbank.org/topic?format:json 400BadRequest
  35. THE GAME NO ONE WANTS TO USE MY API Error in disguise Displaying internals
  36. RESULT FORMATTING Dictating the format will drive developers away
  37. XML IS ON DECLINE Hurray!
  38. POSSIBLE SOLUTIONS URL extensions Query string parameters Content negotiation
  39. THE GAME NO ONE WANTS TO USE MY API Dictation
  40. VERSIONING However perfect you make your web API, you're bound to find a way that's even more perfect before long, and then you'll need to launch a new version.
  41. Capture5 -> Complete / Cancel2
  42. URL VERSIONING GEThttps://api.twitter.com/1.1/trends/place.json?id=1
  43. QUERY STRING PARAMETERS GEThttp://api-public.netflix.com/catalog/titles/series/7002352?v=1.5 GEThttps://api.foursquare.com/v2/venues/40a55d80f964a52020f31ee3?oauth_token=XXX&v=YYYYM
  44. VENDOR SPECIFIC ACCEPT HEADER HEADERAccept:{type}/vnd.{company}.{version}+{type} HEADERAccept:application/vnd.github.v3+json
  45. CUSTOM REQUEST HEADER HEADERx-ms-version:2014-02-14 HEADERapi-version:2
  46. THE GAME NO ONE WANTS TO USE MY API No planning Broken
  47. SUMMARY URI design HTTP Verbs HTTP Status Codes Result Formatting Versioning
  48. QUESTIONS? Thank you! By / /Karoline Klever @karolikl karolikl@gmail.com

×