Bug 1261573

Summary: API docs for incremental update incorrectly mark update_systems[included] as required
Product: Red Hat Satellite Reporter: jaudet
Component: APIAssignee: Zach Huntington-Meath <zhunting>
Status: CLOSED NOTABUG QA Contact: Katello QA List <katello-qa-list>
Severity: medium Docs Contact:
Priority: medium    
Version: 6.1.2CC: adahms, bbuckingham, cwelton
Target Milestone: UnspecifiedKeywords: Triaged
Target Release: Unused   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2016-05-02 20:38:32 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Attachments:
Description Flags
Output of foreman-debug from a RHEL 7.1 system. none

Description jaudet 2015-09-09 17:42:25 UTC
Created attachment 1071860 [details]
Output of foreman-debug from a RHEL 7.1 system.

Document URL: 
https://satellite6.example.com/apidoc/v2/content_view_versions/incremental_update.html

Section Number and Name: 

Describe the issue:
The API docs mark each portion of an API call as either "required" or "optional". The update_systems[included] portion of the `POST /katello/api/content_view_versions/incremental_update` call is marked as required. But this is not true. It's definitely possible to perform an incremental update without specifying this bit of information.

Suggestions for improvement: 

Additional information: 
A test for this issue is in place. This [1] pull request performs an incremental update and passes the following JSON payload:

    payload = {
        'content_view_version_environments': [{
            'content_view_version_id': content_view.version[0].id,
            'environment_ids': [
                environment.id
                for environment
                in content_view.version[0].read().environment
            ],
        }],
        'add_content': {'puppet_module_ids': [puppet_module.id]},
    }

[1] https://github.com/SatelliteQE/robottelo/pull/2739

Comment 1 Andrew Dahms 2016-01-04 06:36:34 UTC
Assigning to Byron for review.

Comment 2 David O'Brien 2016-01-04 07:26:10 UTC
This looks like part of the actual apidoc, not the "API Guide". This would be better raised against the api itself.

Comment 3 David O'Brien 2016-01-15 03:21:00 UTC
Resetting to API component. Docs team doesn't maintain this part of API.

Comment 5 Zach Huntington-Meath 2016-05-02 20:38:32 UTC
This command is now known as update_hosts[included]. This command is a subcommand of the optional command update_hosts. However, if the update_hosts command is given update_hosts[included] is required, which is why it shows up as required in the documentation.