V2: Api docs in foreman should not specify a root node for POST/PUT
See the screenshot. On the left is v2 spec and on the right is the actual apidoc from foreman v2 api.
#3 Updated by Joseph Magen about 8 years ago
The rails default is to return a blank response for PUT and DELETE. Foreman modified the method `api_behavior` in ActionController::Responder to also return object on PUT and DELETE using the rails code
This code is currently used by all POST, PUT, and DELETE requests.
Note that ONLY GET requests use the RABL templates. Return response of POST, PUT, and DELETE did NOT use RABL.
Since this is just for documentation reasons, I suggest to use the Rails standard as is and to change the documentation accordingly.
In short, PUT/POST/DELETE can receive json with OR without a root, but the response will with WITH root node. However, on the GET, the response is WITHOUT rootnode since we configured the RABL templates to do so.
#4 Updated by David Davis about 8 years ago
- Priority changed from High to Low
First of all, this has nothing to do with what's being returned. This has do with the data that's being sent to create/update. So I'm not sure I understand the first part of your comment.
Regarding the second part of your comment, the problem is that the api doc (and thus apipie/hammer requests) is not consistent as in certain parts of the fortello API such as organization, there's no root node whereas other parts of the api such as domain, there is. I think that'll confuse users and create problems for us developers.
This is only documentation so I don't think it's a high priority. However, the apipie (and thus hammer requests, etc) use this documentation so it affects the formats of the requests that are being sent to/from katello and foreman. It's caused issues in the past like http://projects.theforeman.org/issues/4180 was difficult to solve as only half the requests (the un-nested ones) were failing.
I still think we need this but it's not a high priority.
#8 Updated by Dominic Cleal about 8 years ago
- Subject changed from V2: Api docs in foreman should not require a root node for POST/PUT to V2: Api docs in foreman should not specify a root node for POST/PUT
- Status changed from Ready For Testing to New
- Assignee deleted (
- Target version deleted (
Resetting this, because the pull request mentioned changes the response from the API and doesn't change the documentation, as David said. The apipie description of the APIv2 actions includes a wrapped node, which in Foreman's API is optional and as per the documentation (in the screenshot provided) is not used.