Ian McEwen added a comment - 2014-01-13 21:33 (moving out of DR as confirmed in the dev meeting today, using the plan as described)

Oliver Charles added a comment - 2011-10-14 14:17 We agreed these changes are acceptable

Oliver Charles added a comment - 2011-09-27 11:33 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...

Christopher Key added a comment - 2011-07-31 13:19 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>

voiceinsideyou added a comment - 2011-07-31 07:15 Seems related to MBS-2884 and/or MBS-3107 ?