Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Strategy Practice II

API Strategy Practice II

Presentation at Veritrans' weekly sharing session


Panggi Libersa Jasri Akadol

November 08, 2012



  2. APIs : A Strategy Guide

  3. Key Design Principles for APIs

  4. Technical Best Practices from the Tumblr Are there any technical

    best practices from the Tumblr API you’d like to share? ! We want our API to be easy to learn without documentation—the way we lay out our URIs, you should just be able to drop into a command live. ! We try to only slightly tweak the API. One of the big ironies of a website is that I can change it whenever I want, but an API is very brittle in that you can break your developers’ applications. Versioning is an ongoing task. ! Derek Gottfrid, Director of Product, Tumblr
  5. Best Practices for API Design Differentiate Your API Make Your

    API Easy to Try and Use Make Your API Easy to Understand Don’t Do Anything Weird Less Is More Target a Specific Developer Segment
  6. • The data is unique, more complete, or more accurate

    than that of your competitors • You offer better support or an easier signup process • Your API is more robust, reliable, cooler, or faster than alternatives • Your terms are more developer friendly; perhaps you offer more data traffic for free or better rates Differentiate Your API
  7. If your API is one of many options, your audiences

    may dedicate only a few minutes to trying it. If they can’t make almost immediate progress, they’ll go elsewhere. Successful API programs remove all barriers to use. Make Your API Easy to Try and Use
  8. None
  9. “My advice —the simpler, the better. REST, JSON, simple and

    straightforward services. Don’t try to make it too complex. Focus on the core building blocks for an API. Do one thing, do it really well, and bundle it with simple documentation and code samples. These are the essentials of an API.” - Kin Lane, developer evangelist at Mimeo Make Your API Easy to Understand
  10. • Stick to conventions that the developer might already know.

    • Think about using common conventions such as OAuth or other commonly understood security schemes. • This may not only increase adoption but also reduce your (and their) development effort. Don’t Do Anything Weird
  11. Less Is More Successful APIs often start with the absolute

    minimum amount of functionality, and then add functions slowly over time, as feedback is collected.
  12. Target a Specific Developer Segment When launching the API, it

    is important to have expectations about how the service will likely be used so that you can launch an API that satisfies use cases. A : “Who are your target audiences?” B : “Everybody” A : “What kinds of apps do you expect to see built?” B : “All kinds” Wrong:
  13. Technical Considerations for API Design

  14. REST “Representational State Transfer” developed as a PhD dissertation by

    Roy Fielding In essence, Fielding proposed using HTTP for inter-computer communications. Consequently, REST is based on the HTTP standard. Using the building blocks of HTTP, it divides the namespace into a set of “resources” based on unique URI patterns and uses the standard HTTP verbs -- GET, POST, PUT, and DELETE -- to map operations on top of those resources.
  15. None
  16. ...! /getAllDogs! /locationVerify! /foodNeeded! /createRecurringDogWalk! /giveDirectOrder! /healthCheck! /getRecurringDogWalkSchedule! /getLocation! /getDog!

    /massDogParty! /getNewDogsSince! /getRedDogs! /getSittingDogs! /dogStateChangesSearch! /replaceSittingDogsWithRunningDogs! /saveDog! ... A puppy’s world is big.
  17. ...! /getAllDogs! /verifyLocation! /feedNeeded! /createRecurringWakeUp! /giveDirectOrder! /checkHealth! /getRecurringWakeUpSchedule! /getLocation! /getDog!

    /newDog! /getNewDogsSince! /getRedDogs! /getSittingDogs! /setDogStateTo! /replaceSittingDogsWithRunningDogs! /saveDog! ... ...! /getAllLeashedDogs! /verifyVeterinarianLocation! /feedNeededFood! /createRecurringMedication! /doDirectOwnerDiscipline! /doExpressCheckupWithVeterinarian! /getRecurringFeedingSchedule! /getHungerLevel! /getSquirrelsChasingPuppies! /newDogForOwner! /getNewDogsAtKennelSince! /getRedDogsWithoutSiblings! /getSittingDogsAtPark! /setLeashedDogStateTo! /replaceParkSittingDogsWithRunningDogs! /saveMommaDogsPuppies! ...
  18. We are on a slippery slope.

  19. We only need two base URLs per resource.

  20. The first is for a collection.

  21. /dogs

  22. The second is for an element

  23. /dogs/1234



  26. None
  27. Verbs are bad.

  28. Nouns are good.

  29. Plurals or singulars?

  30. Foursquare GroupOn Zappos /checkins /deals /Product

  31. /dogs Plurals are better.

  32. Abstract or concrete naming?

  33. Super High High Medium /things /animals /dogs /beagles Low

  34. /dogs Concrete is better than abstract

  35. What about associations?

  36. GET /owners/1234/dogs POST /owners/1234/dogs

  37. What about complex variations?

  38. /dogs?color=red&state=running&location=park

  39. Error?

  40. None
  41. None
  42. Versioning?

  43. None
  44. /v1/dogs

  45. - What happens to older versions? - What happens to

    apps developed on older versions? - Do new versions support all the functionality of the older apps, or must API customers need to update their apps to work with newer versions? - Do you have a plan for minimizing the number of times you ask developers to upgrade or change versions?
  46. Pagination?

  47. /dogs?limit=25&offset=50

  48. None
  49. /dogs.json /dogs/1234.json

  50. What about non-resource-y stuff?

  51. Calculate Translate Convert

  52. /convert?from=IDR&to=SGD&amount=100 Use verbs not nouns

  53. Searching?

  54. None
  55. What about the rest of the URL?

  56. None
  57. None
  58. What about authentication?

  59. None
  60. OAuth 2.0 Use latest OAuth

  61. Be RESTful Only 2 URLs No verbs Use nouns as

    plurals Concrete over abstract For JSON follow JavaScript conventions Sweep complexity behind the ‘?’ Borrow from leading APIs
  62. Thank You!