Hide Forgot
Document URL: https://access.redhat.com/documentation/en/red-hat-satellite/6.2/paged/api-guide/chapter-4-getting-started-with-the-red-hat-satellite-api Section Number and Name: Describe the issue: The examples give do not explain how they relate to the VERB api-route format of the builtin reference. This makes it harder for someone new to working with APIs to understand how to interpret the information in the API reference. Suggestions for improvement: Make four new simple examples to show how you get from the API route shown in the builtin API reference to a curl, apipie, ruby, and python example. Additional information: Need to explain that because version 2 is the default you do not need to use in in a command and that is wahyv2 does not appear in some parts of the API reference.
Need to explain :value e.g :id or :host_id is an API route parameter
(In reply to Stephen Wadeley from comment #0) <snip> > > Suggestions for improvement: > > Make four new simple examples to show how you get from the API route shown > in the builtin API reference to a curl, apipie, ruby, and python example. > > Martin Bacovsky has suggested it would be better to just have curl examples showing the use of the different HTML verbs. He pointed out SysAdmins wanting to use Ruby or Python are most likely already familiar with HTTP API syntax. That make sense to me. Will do.
Hello Tomas While looking at the builtin reference doc, I noticed this first entry under POST /api/hosts host Validations: required Hash IIUC, that is referring to the API path itself, i.e. the word "host" in /api/hosts If so, would it not be better to alter the script that produces the API reference to suppress that output? Who except a developer would need to know that? I see it under here: POST /api/architectures too. If I look here: POST /katello/api/activation_keys I do not see an entry for activation_keys, so it does not seem to be every were. Thank you
Hello Stephen The error you see is related to missing parameter not to the path. When there's "Hash" validation it means the root node is required in the JSON. In your case the parameters need to be wrapped in {"host": { "name": "somehost", ... }} Unfortunately this isn't consistent across the API. Foreman controllers require the root node while Katello ones take the parameters unwrapped. This is for historical reasons (they started as standalone projects before Katello was rewritten into Foreman plugin). So in the current situation the apidocs should provide a "point of truth" for whether to wrap params or not.
Hello If you do not use an HTML verb it defaults to GET if I recall correctly. So why does Ohad's example[2] have no -X POST ? [2] https://theforeman.org/2012/01/creating-new-host-using-foreman-api.html
Hello These changes are now live in the customer portal. 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