Ask HN: What's Your Favorite API Developer Portal? We're gearing up to redesign our massively outdated Developer Portal and I'd love some examples of API dev portals done right. Folks like Twilio and Tokbox are on the list, who else? Please also say what you like about it and what (if anything) you wish they'd improve. |
FullContact's portal has some nifty navigation on the documentation: http://www.fullcontact.com/developer/docs/
An honorable mention should goto the creativity behind Twitter's Field Guide: https://dev.twitter.com/docs/platform-objects
Mashery also puts together some solid docs via their iodocs system - https://github.com/mashery/iodocs/
a) Keep headings readable (nothing fancy) and un-ambiguous. Don't make me wonder whether I have to go to Authorization or Authentication for instance.
b) Document everything. Even small nuances that you feel are implied. The API specs should change before your API changes.
c) Give me an archived version somewhere. This is easier if you just release your docs as a repo on github. This really helps people out. I ended up converting the parse.com documentation to markdown just to get an offline, readable version for myself.
But definitely look at the oldest developer areas with eBay, Salesforce and Amazon. They have been doing it a while.
Since it's backend as a service, allowing access to view/edit/troubleshoot the data is key.
Also, CloudMailin's (http://www.cloudmailin.com/) 'Try it Live!' is a pretty nice demo of the API.
Mainly tho, I think that the 4sq model of being able to try out every method on the fly is super important to devs...