| Summary: | Add simple API examples | ||
|---|---|---|---|
| Product: | Red Hat Satellite | Reporter: | Stephen Wadeley <swadeley> |
| Component: | Docs API Guide | Assignee: | Stephen Wadeley <swadeley> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | Lucie Jirakova <ljirakov> |
| Severity: | unspecified | Docs Contact: | |
| Priority: | unspecified | ||
| Version: | 6.2.0 | CC: | sauchter, tstrachota |
| Target Milestone: | Unspecified | ||
| Target Release: | Unused | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | If docs needed, set a value | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2017-02-20 15:31:14 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: | |
|
Description
Stephen Wadeley
2016-12-02 13:02:50 UTC
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 |