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.
13 comments
Parse's portal gets a great melding of form, function, and philosophy. http://www.parse.com
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
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
Absolutely agreed on Parse. My only criticism is bookmarking doesn't work very well.
Mashery also puts together some solid docs via their iodocs system - https://github.com/mashery/iodocs/
Mashery also puts together some solid docs via their iodocs system - https://github.com/mashery/iodocs/
What has been your issue bookmarking on Parse?
Not as well known (yet) but Clever has some nifty docs that allow for creating and testing queries against demo data right from the page.
https://getclever.com/developers/docs
https://getclever.com/developers/docs
Stripe does a great job with their portal. Mashery as well has a great interactive portal that I like to use.
Github is also quite good (http://developer.github.com). They are straight forward docs for developer, and the prospect that the complete site is on github itself is a +1. I had some troubles with Cors support recently, and found it part of the spec within two clicks from their main portal. Try to
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.
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.
I second Stripe, Twilio, Tokbox, Dwolla as leaders in good implementation--then add Full Contact, Iron.io, Etsy, Factual and Foursquare to that stack.
But definitely look at the oldest developer areas with eBay, Salesforce and Amazon. They have been doing it a while.
But definitely look at the oldest developer areas with eBay, Salesforce and Amazon. They have been doing it a while.
CloudMine (https://cloudmine.me) recently updated their dashboard, and while I haven't had a chance to really work through it all, it looks pretty nice.s
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.
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.
Pusher has a great realtime console, Stripe has stellar documentation and Foursquare has great developer features like testing recent push notifications.
I actually just rolled out a new Dev portal at Dwolla. He I it out over at developers.dwolla.com. I tried to make it more of an integration portal, so that there's something for coders, but also for non tech people trying to figure out if Dwolla is right for them.
Mainly tho, I think that the 4sq model of being able to try out every method on the fly is super important to devs...
Mainly tho, I think that the 4sq model of being able to try out every method on the fly is super important to devs...
Stripe is pretty spectacular.
Foursquare lets you try out API calls that require authentication without leaving the documentation page. They use the correct permission for your user ID so you can see exactly what a logged in user will get back.
Twilio's getting started documentation blew me away. A focus on what you can build, and what you can get working quickly ("I just sent myself a TEXT. Sweet!"). It's also better designed than most consumer web apps.
Campaign Monitor is pretty awesome: http://www.campaignmonitor.com/api/