Description of problem:

Foreman.Org provided the ansible roles that can be used in the Satellite in API Docs link;

https://apidocs.theforeman.org/katello/4.16/apidoc/v2/ansible_roles.html

and mark the import API as DEPRECATED:

PUT /ansible/api/ansible_roles/import DEPRECATED

However, it is unclear what replaces the deprecated import ansible roles API. Checking further in Jira, this bug is reported, https://issues.redhat.com/browse/SAT-27444

which leads us to test the sync ansible roles  API and indeed it does the same job as import ansible.

For clarity, please include a flag on what API replaces a deprecated one. Or, at least put a description like:

PUT /ansible/api/ansible_roles/sync
Import and Sync Ansible roles

Or, mention the usage of each ansible roles API in Satellite Ansible documentation in a separate section in;

https://docs.redhat.com/en/documentation/red_hat_satellite/6.16/html-single/managing_configurations_by_using_ansible_integration/index#Configuring_Your_satellite_to_Run_Ansible_Roles_ansible

How reproducible: Always

Is this issue a regression from an earlier version: No

Steps to Reproduce:

1. Run below API to import ansible roles in Satellite instead of the deprecate 

    PUT /ansible/api/ansible_roles/import DEPRECATED

Example:

1. curl --trace -k -u admin:redhat -X PUT \
   -H "Accept:application/json" \
   -H "Content-Type: application/json" \
   -d ' { "proxy_id": 1, "role_names": ["linux-system-roles.ad_integration", "linux-system-roles.aide", "linux-system-roles.bootloader", "linux-system-roles.certificate", "linux-system-roles.cockpit"] }
   ' \
   https://sat616.local/ansible/api/ansible_roles/sync \

   python -m json.tool Actual behavior: The ansible API PUT /ansible/api/ansible_roles/sync

works but there is no proper documentation or description this API is an alternative and/or replacement of the import API.

Expected behavior:
There should be a clear description on what the API can do in API link https://apidocs.theforeman.org/katello/4.16/apidoc/v2/ansible_roles.html

or at least ansible roles API section in Satellite Ansible documentation

Business Impact / Additional info:

Some customers are using APi to automate Satellite administration than manual clicks in the WEBUI