API Strategy Practice II

Presentation at Veritrans' weekly sharing session

Transcript

1. API STRATEGY AND PRACTICE Part II
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
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.
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
24. POST GET PUT DELETE
25. CREATE READ UPDATE DELETE
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?
42. Versioning?
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
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?
55. What about the rest of the URL?
58. What about authentication?
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!