API STRATEGY AND PRACTICE Part II 

APIs : A Strategy Guide 

Key Design Principles for APIs 

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 

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 

• 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 

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 

No content

“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 

• 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 

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. 

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: 

Technical Considerations for API Design 

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. 

No content

...! /getAllDogs! /locationVerify! /foodNeeded! /createRecurringDogWalk! /giveDirectOrder! /healthCheck! /getRecurringDogWalkSchedule! /getLocation! /getDog! /massDogParty! /getNewDogsSince! /getRedDogs! /getSittingDogs! /dogStateChangesSearch! /replaceSittingDogsWithRunningDogs! /saveDog! ... A puppy’s world is big. 

...! /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! ... 

We are on a slippery slope. 

We only need two base URLs per resource. 

The first is for a collection. 

/dogs 

The second is for an element 

/dogs/1234 

POST GET PUT DELETE 

CREATE READ UPDATE DELETE 

No content

Verbs are bad. 

Nouns are good. 

Plurals or singulars? 

Foursquare GroupOn Zappos /checkins /deals /Product 

/dogs Plurals are better. 

Abstract or concrete naming? 

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

/dogs Concrete is better than abstract 

What about associations? 

GET /owners/1234/dogs POST /owners/1234/dogs 

What about complex variations? 

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

Error? 

No content

No content

Versioning? 

No content

/v1/dogs 

- 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? 

Pagination? 

/dogs?limit=25&offset=50 

No content

/dogs.json /dogs/1234.json 

What about non-resource-y stuff? 

Calculate Translate Convert 

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

Searching? 

No content

What about the rest of the URL? 

No content

No content

What about authentication? 

No content

OAuth 2.0 Use latest OAuth 

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 

Thank You!