Hide Forgot
Document URL: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/API_Guide/index.html Section Number and Name: Appendix A: permissions Matrix Describe the issue: The usage of the whole of /api/smart_class_parameters/ is poorly described, in fact it only gets a mention in this appendix. Upstream [1] is slightly better in that it actually lists the parameters that you can use, but it provides no information on what you should be passing in to make the API operate. In fact this issue isn't confined to just /api/smart_class_parameters it seems that none of what you need to pass in is actually documented in our documentation, and only barely described in the upstream docs. Compare these docs with the upstream docs for pulp [2] which do actually document properly how to interact with the API. Suggestions for improvement: The documentation should properly describe how to interact with the API, clearly defining what information is expected to be passed in and what effect that this has on the data in satellite. Additional information: [1] - http://www.katello.org/docs/2.4/api/apidoc/smart_class_parameters/update.html [2] - http://pulp.readthedocs.org/en/latest/dev-guide/integration/rest-api/repo/groups/cud.html
Hello Tomas A little bird told me you might be able to provide some /api/smart_class_parameters/ examples that we can use in the API guide. Is that something you could do? Thank you
Hi Stephen, sure I can. The api is documented here: https://<YOUR_SATELLITE>/apidoc/v2/smart_class_parameters.html One of the example API workflows could be overriding values. You can list all smart class params via: GET /api/smart_class_parameters or if you know the puppetclass id you can restrict the scope via: GET /api/puppetclasses/5/smart_class_parameters Both calls accept search parameter. The full list of searchable fields is visible in the UI in search input, but two most useful ones are puppetclass_name and key, which allow you to search for a specific parameter: GET /api/smart_class_parameters Parameters: { "search" => "puppetclass_name = apache and key = apache_version" } Standard scoped-search syntax is supported. Once you found id of the parameter you can proceed with listing full details including current override values: GET /api/smart_class_parameters/63 Now you can allow overriding of parameter values with a put call. Note that there's no way to create or delete the parameters manually. Users can only modify their attributes. Parameters get created/deleted only upon class import from a proxy. PUT /api/smart_class_parameters/63 Parameters: { "smart_class_parameter" => { "override" => true } } Full list of attributes that can be modified is documented here: https://<YOUR_SATELLITE>/apidoc/v2/smart_class_parameters/update.html When override is enabled, you can add custom override matchers. Again, details about all parameters of the API call is here: https://<YOUR_SATELLITE>/apidoc/v2/override_values.html POST /api/smart_class_parameters/63/override_values Parameters: { "override_value" => { "match" => "hostgroup=Test", "value" => "2.4.6" } } To delete override values use: DELETE /api/smart_class_parameters/63/override_values/3 Let me know if you need further details. If you find some of the parameter descriptions insufficient, please open a BZ or send a PR, please. Both will be appreciated. I'm sure your trained eye can provide valuable feedback.
thank you Tomas for comment 8, I will test them. (I might have to configure some Puppet module first.)
Hi Stephen, What do you think of putting them in the section "API Examples Using Curl", at the same level as "Creating and Modifying Resources"? In the ASCIIDoc, are each of the sections at that level a separate file? That would keep our options open and make it easier to reorganize this content later.
Hello These changes are now live on the customer portal https://access.redhat.com/documentation/en/red-hat-satellite/6.2/paged/api-guide/chapter-4-getting-started-with-the-red-hat-satellite-api#sect-API_Guide-Overriding_Smart_Class_Parameters Thank you
Hello As requested, reopening this bug to add some more info based on upstream doc [1] While working on this bug I raised a new bug, BZ#1400966, to add some simple generic examples to explain how you get from the API route or path examples in the built in API reference to a real command. [1] https://docs.pulpproject.org/dev-guide/integration/rest-api/index.html
Hello Tomas As discussed in our meeting: Please provide a list of response codes and any useful hints about them. Thank you
Hi Stephen, the following exit codes are common for all resources in the whole Satellite API: 200 :ok - for any successful request, actions: show, index, update or delete (GET, PUT, DELETE requests) 201 :created - for successful create action (POST request) 301 :moved_permanently - redirect when the satellite is running on https and users hit http 400 :bad_request - a required parameter is missing or the search query has invalid syntax 401 :unauthorized - failed to authorize the user (e.g. wrong credentials) 403 :forbidden - the user has insufficient permissions to perform the action or read the resource, or the action is unsupported in general 404 :not_found - the record with given id doesn't exist - can appear in show and delete actions when the requested record doesn't exist or in create, update and delete actions when one of the associated records doesn't exist 409 :conflict - could not delete deleting the record due to existing dependencies (e.g. hostgoups with children) 415 :unsupported_media_type - the content type of the http request is other than json 422 :unprocessable_entity - failed to create an entity due to some validation errors, create or update actions only 500 :internal_server_error - unexpected internal server error 503 :service_unavailable - the server isn't running
Hello Tomas about the text and colon such as ":ok" When I do "curl -X GET -u admin -I" to see the response codes I see, for example, "Status: 200 OK". I do not know where you saw the colon and the lower case text. Perhaps I should just take the text from an RFC? or from this IANA doc?: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml Thank you
Hi Stephen, the string with colon is a symbol that Ruby on Rails uses. The response code is just the number itself. I agree it will be much better to replace it with the equivalents from the IANA doc. They are the same but human readable (no colons, nu underscores).
Hello as BZ#1400966 is now resolved, we have: Understanding the API Syntax Understanding the JSON Response Format https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/api_guide/chap-red_hat_satellite-api_guide-api_reference as BZ#1416445 is now resolved, we have: Modifying a Smart Class Parameter Using an External File https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/api_guide/chap-red_hat_satellite-api_guide-examples#sect-API_Guide-Modifying_a_Smart_Class_Parameter_Using_an_External_File
This content is live on the Customer Portal. Closing.
Appendix A. API Response Codes https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/api_guide/appe-response_codes