HN Explorer

Ask HN:Mixcloud API - Peer Review

43 points by matclayton ↗ HN
We are slowly opening up our new api, and before full public release, we are putting the api and documentation through peer review. Essentially we would love to know your thoughts as fellow hackers on what you like and hate about the api structure. We accept it isn't perfect, but we can't see our own mistakes as well as others.

If you have a moment please check it out, and any feedback would be greatly appreciated.

http://api.mixcloud.com

[Edit] For those interested, Mixcloud is an online audio hosting platform, focusing on long form audio. This initial launch covers basic site interaction (favorite/follow) and all our meta data. The API authenticated is OAuth2 and JSON(P)/XML endpoints are provided.

13 comments

[ 3.3 ms ] story [ 33.2 ms ] thread
tow21
Haven't had a chance to have more than a very brief look so far; and I don't have any apps in mind just yet. But:

1) massive thumbs up for good use of HATEOS :-) Too many people miss it, and it makes writing clients much easier in my experience (also makes your job much easier in maintaining the API)

2) there's a couple of namespace conflicts which make me itch, but I don't know how important they are in practice. In particular:

http://api.mixcloud.com/spartacus/

http://api.mixcloud.com/popular/ http://api.mixcloud.com/new/ http://api.mixcloud.com/me/

at first glance, I would think that the latter URLS refer to users whose usernames are "popular", "new", and "me". If the endpoints look exactly the same, that's probably ok, but it's still a bit odd. If I'm writing an app which says "enter a username here", I have to remember that these are not valid usernames; and I can imagine similar sort of special-casing might have to be put in elsewhere.

3) I still hate OAuth - it's probably still the best of a bad bunch, though! Nice overview of how to use it in practice.

4) minor issue - for exceeding rate limits, I'd use a 403 code not a 503. 5xx limits boil down to "it's the server's fault". 4xx are "it's your fault" and in this case I think the semantics are more user error than server error.

matclayton
Thanks, for checking it out.

1) Cheers 2) Yeah we know, its a tricky one. We use those urls on the main site, and can't really change those now. The point of the api is to allow any developer to take a url on the site and be able to just swap out the www for api, to get a machine readable version. There are certainly some clashes, the current design decision was it is probably worth it. But we are still gathering responses and this can easily be changed.

3) OAuth1.0 and 1.0a I'd be with you all the way, but become quite a fan of 2.0 its easy to use and to implement, as all the crypto is SSL based.

4) Fair enough, over sight on our point, double checking the meaning and will get it swapped over

Torn
re 2) - you already have /artists/blah and /tag/blah so why not /users/blah ?
matclayton
Turns out our users really like vanity urls :) from an api perspective this makes sense except that it no longer mirrors the main site.
olegp
Wouldn't you be better off exposing internal IDs? As it currently stands your keys and hence URIs are immutable, which could be a problem if somebody wanted to rename things after creating them.

edit: like the way you've emulated Facebook's Graph API wrt metadata - why not go all the way and drop XML support?

matclayton
Potentially, we debated using internal id's. The issue then becomes we dont have a globally unique id currently, so would need to code/make one. We also fix the url's in our system when they are first set and they become immutable.

XML, easy enough for us to do, so why not support it :) we just run it through a different serializer before outputting it. Seemed like a minor addition to keep the XML users happy...

olegp
Just because it's easy, doesn't mean you should include it ;) For one thing it makes the docs longer.

Will be interesting to see how many people use XML.

vyrotek
Great looking site! (listening to mixes as I write this)

So, this is the first time I've heard of you guys. MixCloud is basically a mugasha.com for everyone else, is that correct? Some of my DJ friends were recently looking for something like this. I'll definitely have to pass this along.

I'm still poking around in the API documentation. I'm trying to think of something to make to test it out. What are some example ideas you guys have thought of? I'm sure you guys have thought of some cool ways you'd like to see the API used.

matclayton
Cheers,

We have been around for a while, but tend only to shout in music circles, HN isn't really the right place! We have absolutely no idea what people are going to make on this. We have seen a lot of screen scrapping of our main site, and had loads of emails requesting api access. So figured it was about time we opened it up!

So far have seen guys build last.fm scrobblers, cue timestampers, an android app, and charts, so keen to see what people come up with! We will be setting it in stone for the upcoming Music Hack Day, and sure some interesting stuff will come out of this. http://london.musichackday.org/2010/

Mat

suprgeek
Took a quick look: 1) How do you plan on supporting Versioning in the API? 2) You need to clarify the GET/POST semantics: something like Supported request methods: GET would be helpful 3)As another user pointed out the /me /new etc are a conflict with the existing user namespace
russell_h
+1 for versioning. Without it you are pretty much locked in to what you have now, unless you're willing to flip the switch and break all existing clients.