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
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 trafﬁc for free or better rates Differentiate Your API
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
• 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
is important to have expectations about how the service will likely be used so that you can launch an API that satisﬁes 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:
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.
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?