search

metabrainz / web-service-v3-design

A collaborative specification for the third version of the MusicBrainz web service
2 stars 1 forks source link

Should we use the Link header (RFC 5988)? #3

Open ocharles opened 12 years ago

ocharles commented 12 years ago

RFC-5988 re-defines the Link header, providing a structured language for linking to other resources. In the responses above, I specifically embed the URI to sub-resources, and next/previous page. Perhaps this data would be more useful in the Link header?

warpr commented 12 years ago

I vote for the link headers, specifically moving the first, last, next and prev relations you are currently embedding in the json to the http header. General purpose REST client libraries should in theory already support those for paging through a large result set.

ocharles commented 12 years ago

The problem I see there is: what do you do when you have multiple paged resources? Take the /relationships/ end point - there are 7 paged objects there. That would be 7*4 Link values, which seems a bit unweildly.

warpr commented 12 years ago

The link HTTP headers seem useful to page through a single resource. In that sense they seem natural on the resources you link to from /relationships (i.e. the link headers would be useful on the http://musicbrainz.org/ws/3/artist/:mbid/relationships/artist/ response).

http://musicbrainz.org/ws/3/artist/:mbid/relationships/ then is more of a summary of what is available on each of the actual relationship resources, which perhaps doesn't need the page links, but can suffice with a general link to each of the actual relationship resources. Especially the next/previous links seem unsuitable to be included here.

ocharles commented 12 years ago

I dunno, I do like having the pager links - it's clear that you are viewing a composition of various paged data, and if you wish to continue viewing more in a specific section, you can follow a link to it. Whereas with just linking to /relationships/artist, the client would have to fetch that page just to get the link to page 2 (of course, they could hand code that, but we're attempting to craft something that avoids that need).