[#MBS-3125] collection queries via the webservice are broken - MusicBrainz JIRA

MusicBrainz Server

collection queries via the webservice are broken

Created: 30/Jul/11 09:42 PM Updated: 29/Dec/11 01:31 PM

Component/s:

Collections, Web service

Affects Version/s:

None

Fix Version/s:

None

Issue Links:

Relates

This issue is related to:

~~MBS-3107~~ Retrieving collections via the web service doesn't appear to work correctly

MBS-2884 URL to request releases in a collection is inconsistent

Description

« Hide

The behaviour of collection queries via the webservice is confusion and broken.

At present, any request ending /ws/2/collection returns a collection-list element containing the collections for the currently authenticated user, e.g.,

http://test.musicbrainz.org/ws/2/collection/foobar

returns:

<metadata>
<collection-list>
<collection id="79e457fc-2a99-4a7f-a557-76b9d1ef3a3e">
<name>Collection 2</name>
<editor>cjk32</editor>
<release-list count="1"/>
</collection>
<collection id="ae18570f-c4f9-4fb9-84a5-6f18b811a60d">
<name>Collection 1</name>
<editor>cjk32</editor>
<release-list count="0"/>
</collection>
</collection-list>
</metadata>

This is confusing, and entirely inconsistent with the behaviour for other entities.

To regain consistency with the behaviour for other entities, it should firstly be possible to lookup a single collection via its id. Thus a request for,

.../ws/2/collection/ae18570f-c4f9-4fb9-84a5-6f18b811a60d

should return something like:

<metadata>
<collection id="ae18570f-c4f9-4fb9-84a5-6f18b811a60d">
<name>Collection 1</name>
<editor>cjk32</editor>
<release-list count="0"/>
</collection>
</metadata>

and not simply a complete collection-list as above.

It should also be possible to issue a browse request that does return a collection-list (with data as above). For consistency with other browse requests, I would recommend something like:

.../ws/2/collection?editor=<...>

Any request for a editor other than the current authenticated username would return an http 401 status. It might also be useful to have a 'magic' user value that would indicate that the currently authenticated user should be used.

Finally, there's currently no way to get the content of the release-list for a collection. Adding inc=releases could be used to cause this information to be returned. Alternatively, and probably preferably as release-list is likely to be large (and thus it would probably be desirable to be able to page through the releases), it should be possible to use a browse request, e.g.:

.../ws/2/release?collection=79e457fc-2a99-4a7f-a557-76b9d1ef3a3e

Description

The behaviour of collection queries via the webservice is confusion and broken. At present, any request ending /ws/2/collection returns a collection-list element containing the collections for the currently authenticated user, e.g., http://test.musicbrainz.org/ws/2/collection/foobar returns: <metadata> <collection-list> <collection id="79e457fc-2a99-4a7f-a557-76b9d1ef3a3e"> <name>Collection 2</name> <editor>cjk32</editor> <release-list count="1"/> </collection> <collection id="ae18570f-c4f9-4fb9-84a5-6f18b811a60d"> <name>Collection 1</name> <editor>cjk32</editor> <release-list count="0"/> </collection> </collection-list> </metadata> This is confusing, and entirely inconsistent with the behaviour for other entities. To regain consistency with the behaviour for other entities, it should firstly be possible to lookup a single collection via its id. Thus a request for, .../ws/2/collection/ae18570f-c4f9-4fb9-84a5-6f18b811a60d should return something like: <metadata> <collection id="ae18570f-c4f9-4fb9-84a5-6f18b811a60d"> <name>Collection 1</name> <editor>cjk32</editor> <release-list count="0"/> </collection> </metadata> and not simply a complete collection-list as above. It should also be possible to issue a browse request that does return a collection-list (with data as above). For consistency with other browse requests, I would recommend something like: .../ws/2/collection?editor=<...> Any request for a editor other than the current authenticated username would return an http 401 status. It might also be useful to have a 'magic' user value that would indicate that the currently authenticated user should be used. Finally, there's currently no way to get the content of the release-list for a collection. Adding inc=releases could be used to cause this information to be returned. Alternatively, and probably preferably as release-list is likely to be large (and thus it would probably be desirable to be able to page through the releases), it should be possible to use a browse request, e.g.: .../ws/2/release?collection=79e457fc-2a99-4a7f-a557-76b9d1ef3a3e

Show »

Sort Order:

[ Permalink | « Hide ]

voiceinsideyou added a comment - 31/Jul/11 07:15 AM

Seems related to MBS-2884 and/or ~~MBS-3107~~?

[ Permalink | « Hide ]

Christopher Key added a comment - 31/Jul/11 01:19 PM

Very closely related to MBS-2884, but only peripherally to ~~MBS-3107~~.

The original report was written somewhat hurriedly, a more concise statement might be useful.

I'm suggesting that the API behaves as follows:

1) /ws/2/collection/<collection-id>: A lookup request returning a collection element.
2) /ws/2/collection?editor=<editor>: A browse request returning a collection-list element containing the collections for a given editor. Should return 401 if <editor> doesn't match the authenticated user.
3) /ws/2/release?collection=<collection-id>: A browse request returning a release-list element containing the releases within the given collection.

Requests 2 and 3 should be pageable using the limit and offset parameters, as per any other browse request.

Requests 1 and 2 should allow ?inc=releases. This would cause a release-list element to be present in all collection elements, but it would only contain up to 25 releases. The count attribute for the release-list element would still show the true total.

Request 3 should allow inc=... exactly as per any other browse request for releases.

For reference, a brief summary of lookup, browse and search requests is included below.

MBS-2884 suggests ?inc=releases as a replacement for the very confusing syntax of .../collection/<collection-id>/releases. This is consistent with other parts of the API, but not suitable as the sole means of getting the release-list. It is quite possible that a collection would have many (thousands of) releases, but returning this complete list in a single request is clearly not sensible, and it should instead be possible to page through this list.

Doing this something like:

/ws/2/collection/<collection-id>?inc=releases&limit=<limit>&offset=<offset>

would not be sensible. Throughout the rest of the API, limit and offset are only used for browse and search requests, never for lookups as per the above request. More confusing still would be requests like:

/ws/2/collection?editor=<editor?&inc=releases&limit=<limit>&offset=<offset>

This is a browse request, but the limit of offset parameters would not be working on the top-level collection-list, but multiple release-lists within each collection element. Throughout the rest of the API, the limit and offset parameters always operate on the top-level list.

This is why I suggest the request 3 above: If a client only wants a the first 25 releases in a collection, they can use request 1 or 2. If a client wants more than the first 25 releases in a collection, they can then issue request 3 to page through them. This is precisely analogous to the way the rest of the API works. For example, consider:

http://musicbrainz.org/ws/2/artist/614e3804-7d34-41ba-857f-811bad7c2b7a?inc=releases

This returns an artist, with a release-list element with a count attribute of 129, but only 25 releases within it. To get at the remaining releases, I can then perform requests:

http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=0
http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=25
http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=50
...
http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=125

When dealing with collections, I would request:

http://musicbrainz.org/ws/2/collection/00000001-0002-0003-0004-000000000005?inc=releases

This would return a collection with a release-list element with some count value (say, 128), but only 25 release within it. To get at the remaining releases, I would perform requests:

http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=0
http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=25
http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=50
...
http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=125

Finally, as noted above, the inc parameters available when browsing releases by collection should be exactly the same as when browsing releases by any other entity, e.g.:

http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=0&inc=labels
http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=0&inc=labels

should both cause the returned release elements to contain a label-info-list element.

The webservice supports three types of requests: lookup, browse and search.

A lookup request is of the form:

/ws/2/<entity>/<entity-id>?inc=<inc>

and returns data in the form:

A browse request is of the form:

/ws/2/<entity>?<rel-entity>=<rel-entity-id>&inc=<inc>&limit=<limit>&offset=<offset>

and returns data of the form:

A search request is of the form:

/ws/2/<entity>?query=<query>&inc=<inc>&limit=<limit>&offset=<offset>

and returns data of the form:

[ Show » ]

Christopher Key added a comment - 31/Jul/11 01:19 PM Very closely related to MBS-2884, but only peripherally to ~~MBS-3107~~. The original report was written somewhat hurriedly, a more concise statement might be useful. I'm suggesting that the API behaves as follows: 1) /ws/2/collection/<collection-id>: A lookup request returning a collection element. 2) /ws/2/collection?editor=<editor>: A browse request returning a collection-list element containing the collections for a given editor. Should return 401 if <editor> doesn't match the authenticated user. 3) /ws/2/release?collection=<collection-id>: A browse request returning a release-list element containing the releases within the given collection. Requests 2 and 3 should be pageable using the limit and offset parameters, as per any other browse request. Requests 1 and 2 should allow ?inc=releases. This would cause a release-list element to be present in all collection elements, but it would only contain up to 25 releases. The count attribute for the release-list element would still show the true total. Request 3 should allow inc=... exactly as per any other browse request for releases. For reference, a brief summary of lookup, browse and search requests is included below. MBS-2884 suggests ?inc=releases as a replacement for the very confusing syntax of .../collection/<collection-id>/releases. This is consistent with other parts of the API, but not suitable as the sole means of getting the release-list. It is quite possible that a collection would have many (thousands of) releases, but returning this complete list in a single request is clearly not sensible, and it should instead be possible to page through this list. Doing this something like: /ws/2/collection/<collection-id>?inc=releases&limit=<limit>&offset=<offset> would not be sensible. Throughout the rest of the API, limit and offset are only used for browse and search requests, never for lookups as per the above request. More confusing still would be requests like: /ws/2/collection?editor=<editor?&inc=releases&limit=<limit>&offset=<offset> This is a browse request, but the limit of offset parameters would not be working on the top-level collection-list, but multiple release-lists within each collection element. Throughout the rest of the API, the limit and offset parameters always operate on the top-level list. This is why I suggest the request 3 above: If a client only wants a the first 25 releases in a collection, they can use request 1 or 2. If a client wants more than the first 25 releases in a collection, they can then issue request 3 to page through them. This is precisely analogous to the way the rest of the API works. For example, consider: http://musicbrainz.org/ws/2/artist/614e3804-7d34-41ba-857f-811bad7c2b7a?inc=releases This returns an artist, with a release-list element with a count attribute of 129, but only 25 releases within it. To get at the remaining releases, I can then perform requests: http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=0 http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=25 http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=50 ... http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=125 When dealing with collections, I would request: http://musicbrainz.org/ws/2/collection/00000001-0002-0003-0004-000000000005?inc=releases This would return a collection with a release-list element with some count value (say, 128), but only 25 release within it. To get at the remaining releases, I would perform requests: http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=0 http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=25 http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=50 ... http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=125 Finally, as noted above, the inc parameters available when browsing releases by collection should be exactly the same as when browsing releases by any other entity, e.g.: http://musicbrainz.org/ws/2/release?artist=614e3804-7d34-41ba-857f-811bad7c2b7a&limit=25&offset=0&inc=labels http://musicbrainz.org/ws/2/release?collection=00000001-0002-0003-0004-000000000005&limit=25&offset=0&inc=labels should both cause the returned release elements to contain a label-info-list element. The webservice supports three types of requests: lookup, browse and search. A lookup request is of the form: /ws/2/<entity>/<entity-id>?inc=<inc> and returns data in the form: <metadata> <entity id="..."> ... </entity> </metadata> A browse request is of the form: /ws/2/<entity>?<rel-entity>=<rel-entity-id>&inc=<inc>&limit=<limit>&offset=<offset> and returns data of the form: <metadata> <entity-list count="..." offset="..."> <entity id="..."> ... </entity> <entity id="..."> ... </entity> ... </metadata> A search request is of the form: /ws/2/<entity>?query=<query>&inc=<inc>&limit=<limit>&offset=<offset> and returns data of the form: <metadata> <entity-list count="..." offset="..."> <entity id="..."> ... </entity> <entity id="..."> ... </entity> ... </metadata>

[ Permalink | « Hide ]

Oliver Charles added a comment - 27/Sep/11 11:33 AM

We'll need to talk about this as we're changing the API, but I agree with everything Christopher says. The problem is mostly the API changes though...

[ Permalink | « Hide ]

Oliver Charles added a comment - 14/Oct/11 02:17 PM

We agreed these changes are acceptable