| Summary: | API Documentation: Retrieving a single Distribution should not return an array | ||
|---|---|---|---|
| Product: | [Retired] Pulp | Reporter: | Peter Meier <peter.meier> |
| Component: | documentation | Assignee: | Pradeep Kilambi <pkilambi> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | Preethi Thomas <pthomas> |
| Severity: | unspecified | Docs Contact: | |
| Priority: | unspecified | ||
| Version: | 1.0.0 | CC: | skarmark |
| Target Milestone: | --- | Keywords: | Triaged |
| Target Release: | Sprint 30 | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2012-02-24 20:10:39 UTC | Type: | --- |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
|
Description
Peter Meier
2011-11-10 13:02:11 UTC
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. |