

Ask HN:Mixcloud API - Peer Review - matclayton

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.<p>If you have a moment please check it out, and any feedback would be greatly appreciated.<p>http://api.mixcloud.com<p>[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.
======
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.

------
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.

------
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

------
exline
The API looks good to me. Nicely documented. Only found one thing that seems
wrong.

You have: <http://api.mixcloud.com/popular/>
<http://api.mixcloud.com/popular/hot/> <http://api.mixcloud.com/new/>

<http://api.mixcloud.com/popular/hot/> seems like it should be
<http://api.mixcloud.com/hot/> to be consistent.

------
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.

------
s2r2
clicky <http://api.mixcloud.com>

