Hide Forgot
Description of problem: https://fedorahosted.org/pulp/wiki/UGREST-Distributions shows that using GET /distribution/<distribution id>/ (Mind that here the s is also messing, see #752791) Will return a single distribution, however the response example shows that it returns an array containing one distribution. With respect to retrieve other objects such as a repository or a task, this should return also one item which not contained in an array. Note: Due to some other bugs, I couldn't yet import any distribution, so I wasn't yet able to verify what it actually returns. So either the documentation should be fixed or the code adjusted. As I was unsure whether the wiki documentation is autogenerated or not, I went with filing a bug report.
I disagree with this. It's cumbersome in code to have to check if the return value is a single value or a list. It leads to branching code paths that either loop or deal directly with the return. It's often simpler to just assume you'll be able to loop, even if it's one item. It's possible the repository/task APIs you mention are the ones that are incorrect. Granted, our APIs still need some work, so those inconsistencies are likely there. I think the emerging convention is that a "get" method will return 0 or 1 item whereas a "find" will always return a list (even if the list is empty when there are no matching items). The issue is that we have yet to get to the point where that's implemented across the board :)
Coming from a Rails-Webservice background, getting an array, by explicitly asking for one resource (GET with <unique-id>) is somehow weird. However, I'm not that deep into REST-Webservice architectures, so I cannot argue what the common standard or convention is. Imho REST is not standardized in that specific question, but I was not able to quickly find a single example of another REST-Api where GET /resources/<id> returns an array, but I found plenty of examples that says that GET /resources/ returns an array of all items, while GET /resources/<id> returns exactly one item, *not* contained in an array. See for example: * http://developer.github.com/v3/gists/ * http://www.xfront.com/REST-Web-Services.html (Very quickly searched examples) It is you're decision how you like to implement things, but it's probably a good idea to follow the common implementation amongst other webservices. Anyway, as long as it is consistently implemented amongst all other objects of your API I would already be happy. Having 2 different kind of answers for the same kind of request (GET with <unique-id>) against the same API simply leads to cumbersome code on the other side of the API.
You're right to look at it from the REST perspective. When I made the get/find distinction, I was thinking about internal APIs and not that these were going through HTTP GET calls. I'm with you on the consistent implementation, that part definitely has to be addressed.
Ah ha, now I remember what I was thinking of. https://fedorahosted.org/pulp/wiki/RestApiDevelopment That's our REST policy. That talks about retrieving a single resource v. a collection. So: GET /repositories/foo/ will return a single object or none. GET /repositories/ will return a list or empty list That's what I meant to say back when I talked about get v. find. :) Now we just need to finish migrating the APIs to match that.
This was just a doc issue. We indeed return a single object instead of a list. The doc is now updated with the right response example. I'm also changing the 'distribution' to 'distributions' for consistency(#752791), so be prepared to update your code for the next build. :)
build: 0.249
verified
Pulp v1.0 is released Closed Current Release.