How human is the Viddler API?

Have no idea about API design but would like to learn more? Check out our API Webinar.

After reading Noah Lorang of 37signal’s post API design for humans I got to thinking… how human is the Viddler API?

We agree with Noah. It is now more important than ever to have a solid API design, documentation, and example code at the ready if you’d like your platform or service to be used by others in their applications. We’ve always held this to be true and that is why we’ve always strived to have a comprehensive API and a site dedicated to developers and their use of our API.

So, lets take an honest look at ourselves using Noah’s post as our lens to see how the Viddler API design stacks up to being friendly for humans.

Clear documentation

Noah points out that even if the API is a mess clear documentation can make up for it. Lets go through Noah’s definition of what he considers clear API documentation to see if Viddler makes the cut with a “rating” of how we did.

• Examples that show the full request. (3 out of 5 stars) Noah cites two good examples of how to show the full request. Viddler’s documentation aligns with his second example in that we show the request URL with the expected response. While we include the full request for most methods we do not include them for every method. We’ll update our documentation today to include full request examples for all methods.
• Examples that show the expected response (4 out of 5 stars) We have expected responses for every method of our API. We also have a fairly comprehensive API Explorer that allows you to choose any API method, type in a few arguments and get a live response from the API in any of our supported formats. I could have rated us 5 out of 5 on this one but I’ll tell you why I didn’t; we don’t feel like we’re done with our API Explorer. We’ve got some planned updates to it that should make it even easier to use. So stay tuned for those updates!
• List of API error codes, what they mean, and the most common cause of receiving them (5 out of 5 stars) Our documentation includes a thorough description of each error code you could receive and their possible causes. In fact, our API doesn’t just return an error code when something goes wrong it includes the entire description and possible cause with the response.
• Communication of versioning and depreciating schedules (5 out of 5 stars) We think we’ve given people very fair warning about the depreciation of the first version of our API. In fact, it has been a year since we announced version 2 of our API and we still haven’t fully gotten rid of it (though we will be sometime this year so please, please move your applications over). We’ve tried to over communicate this update so that people have ample time to update their applications, wrappers, plugins. Something else that Noah mentioned is showing developers how to upgrade from version 1 to version 2 of our API. We’ve done this in a few ways; first, we’ve got a transition guide, and second we’ve actually built a “transition wrapper” in PHP to help people move from one version to another. We hope this has been sufficient.

Authentication methods

Noah pointed out that while there are several ways to handle API authentication (OAuth, User/Pass, HTTP Basic Auth, etc) each of them have their plusses and minuses. So he’d prefer it if an API offered multiple types of authentication. As of today Viddler’s API only uses user/pass with a token that we call sessionID for authentication. We know we have work to do in this area and we plan on adding additional methods of authentication to our API in the future.

API design best practices

Finally Noah muddles through some underlying design practices for REST APIs and mentions that while he doesn’t care if an API is a fully RESTful API in the strictest sense he does prefer that it follow at least a few general rules. Again, lets go through these and see how the Viddler API’s underlying design stacks up to his preferences.

• Not SOAP (5 stars) Our API is not SOAP.
• HTTP verbs mean something (5 stars) The Viddler API makes explicit use of GET, POST, PUT based on the method being called. This way the developer is sure that when using GET no data will be affected but when using POST it will be.
• Sensible resource names (unsure stars) I’m not sure how to rate this one. Noah likes resource names to make sense and so do we. He cites URL examples like /posts/23 instead of /api?type=post&id=23. Our URLs are sort of a mix. The method and format is in the URL but the arguments are in the query string. E.g. api/viddler.users.auth.json?user=USERNAME&password=PASSWORD I’m not sure how Noah would grade us on this one.
• XML and JSON support (5 stars) We support XML, JSON, and PHP formatted responses with our API. We considered supporting LOLcats like Flickr but who has the time?
• Abstraction where useful In short, this means that there should be methods for common tasks rather than relying on the developer to have long workflows for simple things. A good example of this, on the Viddler API, is the viddler.videos.comments.add and viddler.videos.comments.remove methods. These are two common tasks that are wrapped neatly into their own methods so that developers can add and remove comments quickly without a lot of code.

Noah’s post was a great opportunity to take an honest look at how Viddler’s API and documentation look to a human outside of Viddler’s offices. We have a few things to work on but overall we’re proud of how our API design is performing for our customers and we hope you are happy to use it.