-
Notifications
You must be signed in to change notification settings - Fork 95
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Modularize content in "guides/common/modules" related to the Foreman API guide * Unifying anchors Is a original effort by Lena to bring the Foreman API guide upstream, we briefly discussed to way to set anchors. If I remember correctly, we though about using the api- prefix similar to the cli- prefix for CLI procedures. I consider this to have value on its own; and allow for a smoother transition in case we ever decide that we want to also show the API procedure as part of "normal aka. WebUI-based" workflows. * Using long options for commands (mostly curl) to provide better readability * Using one argument per line to also simplify readability
- Loading branch information
1 parent
27cc32d
commit df5282e
Showing
35 changed files
with
956 additions
and
790 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -13,186 +13,3 @@ Examples in this section include the password only for the sake of simplicity. | |
| Be aware that if you use the `--silent` option, `curl` does not display a progress meter or any error messages. | ||
|
|
||
| Examples in this chapter use the Python `json.tool` module to format the output. | ||
|
|
||
| [id="sect-API_Guide-Passing_JSON_Data_with_the_API_Request"] | ||
| == Passing JSON data to the API request | ||
|
|
||
| You can pass data to {ProjectServer} with the API request. | ||
| The data must be in JSON format. | ||
| When specifying JSON data with the `--data` option, you must set the following HTTP headers with the `--header` option: | ||
|
|
||
| ---- | ||
| --header "Accept:application/json" \ | ||
| --header "Content-Type:application/json" | ||
| ---- | ||
|
|
||
| Use one of the following options to include data with the `--data` option. | ||
|
|
||
| .JSON-formatted string | ||
| Enclose the quoted JSON-formatted data in curly braces `{}`. | ||
| When passing a value for a JSON type parameter, you must escape quotation marks `"` with backslashes `\`. | ||
| For example, within curly braces, you must format `"Example JSON Variable"` as `\"Example JSON Variable\"`: | ||
|
|
||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| --data {"id":44, "smart_class_parameter":{"override":"true", "parameter_type":"json", "default_value":"{\"GRUB_CMDLINE_LINUX\": {\"audit\":\"1\",\"crashkernel\":\"true\"}}"}} | ||
| ---- | ||
|
|
||
| .JSON-formatted file | ||
| The unquoted JSON-formatted data enclosed in a file and specified by the `@` sign and the filename. | ||
| For example: | ||
|
|
||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| --data @_file_.json | ||
| ---- | ||
|
|
||
| Using external files for JSON formatted data has the following advantages: | ||
|
|
||
| * You can use your favorite text editor. | ||
| * You can use syntax checker to find and avoid mistakes. | ||
| * You can use tools to check the validity of JSON data or to reformat it. | ||
|
|
||
| Use the `json_verify` tool to check the validity of the JSON file: | ||
|
|
||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| $ json_verify < _file_.json | ||
| ---- | ||
|
|
||
| [id="sect-API_Guide-Performing_Simple_Queries"] | ||
| == Retrieving a list of resources | ||
|
|
||
| This section outlines how to use `curl` with the {ProjectX} API to request information from {Project}. | ||
| These examples include both requests and responses. | ||
| Expect different results for each deployment. | ||
|
|
||
| .Listing users | ||
|
|
||
| This example is a basic request that returns a list of {Project} resources, {Project} users in this case. | ||
| Such requests return a list of data wrapped in metadata, while other request types only return the actual object. | ||
|
|
||
| Example request: | ||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| $ curl --request GET --user _My_User_Name_:__My_Password__ \ | ||
| https://_{foreman-example-com}_/api/users | python3 -m json.tool | ||
| ---- | ||
|
|
||
| Example response: | ||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| { | ||
| "page": 1, | ||
| "per_page": 20, | ||
| "results": [ | ||
| { | ||
| "admin": false, | ||
| "auth_source_id": 1, | ||
| "auth_source_name": "Internal", | ||
| "created_at": "2018-09-21 08:59:22 UTC", | ||
| "default_location": null, | ||
| "default_organization": null, | ||
| "description": "", | ||
| "effective_admin": false, | ||
| "firstname": "", | ||
| "id": 5, | ||
| "last_login_on": "2018-09-21 09:03:25 UTC", | ||
| "lastname": "", | ||
| "locale": null, | ||
| "locations": [], | ||
| "login": "test", | ||
| "mail": "[email protected]", | ||
| "organizations": [ | ||
| { | ||
| "id": 1, | ||
| "name": "Default Organization" | ||
| } | ||
| ], | ||
| "ssh_keys": [], | ||
| "timezone": null, | ||
| "updated_at": "2018-09-21 09:04:45 UTC" | ||
| }, | ||
| { | ||
| "admin": true, | ||
| "auth_source_id": 1, | ||
| "auth_source_name": "Internal", | ||
| "created_at": "2018-09-20 07:09:41 UTC", | ||
| "default_location": null, | ||
| "default_organization": { | ||
| "description": null, | ||
| "id": 1, | ||
| "name": "Default Organization", | ||
| "title": "Default Organization" | ||
| }, | ||
| "description": "", | ||
| "effective_admin": true, | ||
| "firstname": "Admin", | ||
| "id": 4, | ||
| "last_login_on": "2018-12-07 07:31:09 UTC", | ||
| "lastname": "User", | ||
| "locale": null, | ||
| "locations": [ | ||
| { | ||
| "id": 2, | ||
| "name": "Default Location" | ||
| } | ||
| ], | ||
| "login": "admin", | ||
| "mail": "[email protected]", | ||
| "organizations": [ | ||
| { | ||
| "id": 1, | ||
| "name": "Default Organization" | ||
| } | ||
| ], | ||
| "ssh_keys": [], | ||
| "timezone": null, | ||
| "updated_at": "2018-11-14 08:19:46 UTC" | ||
| } | ||
| ], | ||
| "search": null, | ||
| "sort": { | ||
| "by": null, | ||
| "order": null | ||
| }, | ||
| "subtotal": 2, | ||
| "total": 2 | ||
| } | ||
| ---- | ||
|
|
||
| [id="sect-API_Guide-Creating_and_Modifying_Resources"] | ||
| == Creating and modifying resources | ||
|
|
||
| You can use `curl` to manipulate resources on your {ProjectServer}. | ||
| API calls to {Project} require data in `json` format. | ||
| For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. | ||
|
|
||
| [id="ex-API_Guide-Creating_a_New_User"] | ||
| .Creating a user | ||
|
|
||
| This example creates a user by providing required information in the `--data` option. | ||
|
|
||
| Example request: | ||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| $ curl --header "Accept:application/json" \ | ||
| --header "Content-Type:application/json" --request POST \ | ||
| --user _My_User_Name_:__My_Password__ \ | ||
| --data "{\"firstname\":\"_Test Name_\",\"mail\":\"[email protected]_\",\"login\":\"_test_user_\",\"password\":\"_password123_\",\"auth_source_id\":__1__}" \ | ||
| https://_{foreman-example-com}_/api/users | python3 -m json.tool | ||
| ---- | ||
|
|
||
| .Modifying a user | ||
|
|
||
| This example modifies given name and login of the `test_user` that was created in xref:ex-API_Guide-Creating_a_New_User[]. | ||
|
|
||
| Example request: | ||
| [options="nowrap", subs="+quotes,attributes"] | ||
| ---- | ||
| $ curl --header "Accept:application/json" \ | ||
| --header "Content-Type:application/json" --request PUT \ | ||
| --user _My_User_Name_:__My_Password__ \ | ||
| --data "{\"firstname\":\"_New Test Name_\",\"mail\":\"[email protected]_\",\"login\":\"_new_test_user_\",\"password\":\"_password123_\",\"auth_source_id\":__1__}" \ | ||
| https://_{foreman-example-com}_/api/users/_8_ | python3 -m json.tool | ||
| ---- | ||
Oops, something went wrong.