I’m about to finish writing the web service (version 1 & 2) for NGS, based on the work that Lukas started a few months ago. The NGS web service currently does not have a compete means of tweaking how much XML is returned for a given resource. Lukas wondered if we should keep our existing approach or start using a new approach that Last.fm (and others) use.
Compare our current approach:
/ws/1/release-group/052c7adb-5e2d-3cf3-b303-6c2a7d3e5b1c/?type=xml&inc=releases (docs)
to the Last.fm approach:
/2.0/?method=album.getinfo&artist=Cher&album=Believe (docs)
Should we keep our current resource focused URL structure or move to a method centric approach in our v2?
If you’re a fan of the old skool structure, please leave a comment and tell us what could be improved. What do you like about the web service? What do you hate?
For some background — as of the NGS release we will be making a lot of changes:
- the old RDF web service will no longer work.
- The old v1 XML interface will continue to work, but not optimally since we will be shoe-horning the spiffy new NGS XML into the old skool v1 XML. Concepts like artist-credits and works will not be available in the v1 compatibility interface.
- The new v2 XML interface will expose all the NGS goodies like artist-credits and works.
MetaBrainz Blog 
Both methods will do, as long as they expose the same functionality. Though, keeping the current approach will make it easier for users to migrate to v2.
Thanks for all the hard work you’ve put into the NGS!
I’d prefer the current approach. One particularly interesting article I read recently on the very subject:
http://duncan-cragg.org/blog/post/strest-service-trampled-rest-will-break-web-20/
Might be worth reading before you decide one way or another.
I mostly use the web service to get information on a particular artist or release, so I like that the current scheme is very focused on MBIDs. I’m not a particularly heavy user though.
The latter approach is no longer REST in the strict sense. Instead of resources, it’s an RPC style design. I’m sure you can get both styles working, but you’d need a bit more work to port existing libraries.
People are likely to understand RPC style better (REST is hard, as we know), but personally, I don’t like it much. Being one of the designers of the old web service, I’d hate to see it dumbed down 🙂
The reason why I suggested the RPC-style WS is because it’s not easy to put all the useful functionality to the to the document-style service.
For example, it might be useful to get a list of release groups for a label, but they are not directly related to labels, so having a element in is not very clean solution.
Or if I want to get folksonomy tags for an entity, the service needs to load and return the entity first, which is not necessary in many cases.
The current web service is also quite inconsistent because of this: Submitting track ISRCs is a POST request to /ws/1/track, but submitting track tags is a POST request to /ws/1/tag (but getting tags back is a GET request to /ws/1/track/MBID?inc=tags).
Another example are micro-APIs, such as searching by URLs. It’s useful to look up artist by Wikipedia URL, but there is no clean way to implement it right now.
Sorry but I don’t understand the example, would be better if you showed the two ways to get the same thing, the first is clearly looking up a specific release group, not sure if the second is looking up a particular album or searching for an album. Nor do I understand the benefits of Lukas’es approach I’m sure there are some but I can’t see what they are, need more detail.
Purely on a practical level I would prefer to keep the existing method because it will be easier for client applications to migrate, and because you won’t fix bug #5448 the existing V1 interface is going to be essentially broken shortly after the NGS release.
Please stay with the resources, making it more REST-like rather than RPC. Read up on the dialog series with the imaginary eBay architect for more info on REST. HATEOAS rocks.
I really like the current MusicBrainz XML API – it is logical, well structured and RESTful.
The last.fm API is not very RESTful or web-like and smells of RPC.
Well, the last.fm approach seems to be non-RESTful, whereas the current MB API is. If you adopted this, you’d no longer be providing a uniform interface to a taxonomy of resources, but rather apparently providing a single endpoint for all queries. I could go into all of the downsides to such an approach, but I presume those who designed the v1 API are alive to such issues.
A method-centric URL approach would be a lot easier to read/parse by the eye, which isn’t incredibly important but is pretty nice. Intelligible URLs make using a particular site that much nicer.
Would it have any effect on the server load?
Great article cited by CBT above, worth reading IMHO.
Very good article indeed. I strongly suggest to keep the ressource-based method. last.fm can afford to be fuzzy. Their Webservice seems more like an implementation of a search. As long as it returns *something* (that users can listen to), users will be happy. MusicBrainz is much more about exact data on exactly this ressource (identified by an MBID). Therefore MB cannot afford to be fuzzy.
Maybe you could think of creating a good and simple to use webservice to the search engine that returns lists of MBIDs and then people can use the Webservice to the MB database to get the details on these items if they want. (does that make sense?)
I used to think HATEOAS was purely theoretical nonsense, but after looking at Why HATEOAS? I can see some real benefits.
Ideally, clients shouldn’t need to worry too much about constructing URLs, because they can all be navigated from a single point of entry. The entry point would have the equivalent of search forms from which one could construct the query. Also, instead of using MBIDs to link things together, simply use the URLs at which that resource can be found – no URL construction needed.
Certainly, some of these ideas require a bit more effort on the client side (I think, I haven’t actually coded against such a service). On the actual question, I support the resource-centric view and using an XML equivalent of HTML search forms for search queries which aren’t themselves resources.
I also like the REST-style MusicBrainz resources – they’re clear and easy to use. If there are no major compatibility problems with the new features of NGS then I’d suggest to keep them because I think adopting the web service to a new style causes more work than benefits on both client and server side.
Thank you for your work on this API. I think it’s a very important part of the MusicBrainz architecture.
I may be underprepared to answer your questions, because a) I haven’t written code to the existing APIs and b) I don’t understand what you are asking.
But one thing that I do know, is that I want the new APIs to enable the creation of a more productive data entry application for classical music releases. This is a application which lets the user enter in all the data about a multi-CD recording, including names of performers, in a single session. The app accepts partial performer, work, release, label etc. names from the user, does query to find candidate MB entities for that item, then presents the candidates in a menu for the user to select. Finally, when everything looks OK, the user tells the application to submit. The application breaks the data into multiple data entry submissions for the work, the release, the discs, the Advanced Relationships, etc., all from that one user action.
So, if one of the alternatives you are posing makes the above scenario difficult to achieve, then I have an objection to that alternative.
I’ve tried to follow the discussion and arguments in favour of REST. And note the suggestion that version2 of audioscrobbler’s API (last.fm), smells of RPC.
ws.audioscrobbler.com/1.0/user/rj/weeklychartlist.xml
ws.audioscrobbler.com/2.0/?method=user.getweeklychartlist&user=rj&api_key=blahblahblah
But I cannot see much difference apart from the format of the uri. You can get to both through a URI, they are both RESTful, are they not?
There is a trend towards clean uris, which don’t show a classic query string. But why are they better? If anything the second example above is easier to understand? Who cares about the order of arguments? Surely proxys tackled this problem, from the good old CGI days?
The first example indicates I am getting an XML response. Which is clear. Although the second, example allows alternative formats (add format=json), Which is also nice.
I could understand that using basic authentication might be better than adding the api-key. So I could share the link. Cache more easily (perhaps). But I also understand the need for tracking the API use.
So I’m left slightly confused and have no particular preference.
As long as the existing API remains, and all the API’s are clearly documented I can’t see a problem. A simple crib sheet.
For me, it’s great to share a URI, and in a perfect world it’s also easy to write down. As a web dev, I like to look at the URI – I have a morbid fascination.
Take: http://example.com/node/34 vs http://example.com/blog/should-i-upgrade-my-api
The first is more usable as I can write it down. I can always make it more descriptive by use of an a element in html. When I’m actually viewing the resource though, the title is more important in HTML than the uri. Should I care what an API uri looks like? Surely both are as easy to construct from a developers perspective.
Am I missing something obvious here?