Bug 1327678

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