The below examples illustrate how to use the ManageIQ REST API with the Client for URLs (cURL), Ruby and Python. All examples shown use the default admin credentials with insecure methods.
Three basic examples will be shown, a GET, a POST with a simple payload and a GET with filtering
All examples use IP Address 192.0.2.0 to represent the ManageIQ appliance, with the default HTTPS port omitted.
cURL
The cURL command can be used from the shell. However the shell’s interpretation of some characters, for example &, can make it awkward to use for complex cases. To help alleviate this the payload can be passed to cURL using the --data flag, where the JSON payload is provided in a file.
The JSON returned is formated in the examples using python -m json.tool
Example 1: A simple GET with cURL
Get the collection groups
curl --user admin:smartvm --insecure --request GET https://192.0.2.0/api/groups | python -m json.tool
Example 2: Using POST to edit a group with cURL
Edit an instance of the collection groups
In this example the payload data is read from a file.
$ cat request.json { "action" : "edit", "resource" : { "description" : "updated group description from cURL" } }
Use the data in file request.json to edit an instance of the collection groups
curl --data @request.json \ --header "Content-Type: application/json" \ --user admin:smartvm \ --insecure \ --request POST https://192.0.2.0/api/groups/23 | python -m json.tool
Example 3: A GET using filtering with cURL
Filtering can be done by passing parameters in the URL. Parameters are preceded by the & character, which can cause problems as the shell interprets the & character as an instruction to: run this command in the background. To avoid this the parameters can instead be passed to curl using the --get flag combined with each parameter being passed with the --data flags.
curl --user admin:smartvm \ --insecure \ --request GET \ --header "Content-Type: application/json" https://192.0.2.0/api/groups \ --get \ --data "expand=resources" \ --data "attributes=description,miq_user_role_name" \ --data "filter[]=miq_user_role_name='*user*'" | python -m json.tool
Example 3: Result
Result truncated and showing only the returned resources.
... "resources": [ { "description": "EvmGroup-user", "href": "https://192.0.2.0/api/groups/4", "id": "4", "miq_user_role_name": "EvmRole-user" }, { "description": "EvmGroup-vm_user", "href": "https://192.0.2.0/api/groups/9", "id": "9", "miq_user_role_name": "EvmRole-vm_user" }, { "description": "EvmGroup-user_self_service", "href": "https://192.0.2.0/api/groups/12", "id": "12", "miq_user_role_name": "EvmRole-user_self_service" }, { "description": "EvmGroup-user_limited_self_service", "href": "https://192.0.2.0/api/groups/13", "id": "13", "miq_user_role_name": "EvmRole-user_limited_self_service" } ], ...
Ruby
The same three examples shown above are illustrated here using Ruby.
The ManageIQ hostname or IP Address is being made available through the environment variable MIQ :
export MIQ="192.0.2.0"
Example 1: A simple GET with Ruby
Get the collection groups
#!/usr/bin/env ruby require 'json' require 'net/http' require 'openssl' require 'uri' uri = URI.parse("https://#{ENV['MIQ']}/api/groups") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Get.new(uri.request_uri) request.basic_auth("admin", "smartvm") response = http.request(request) puts "Reply:\n " + JSON.pretty_generate(JSON.parse(response.body.strip))
Example 2: Using POST to edit a group with Ruby
Edit an instance of the collection groups
#!/usr/bin/env ruby require 'json' require 'net/http' require 'openssl' require 'uri' uri = URI.parse("https://#{ENV['MIQ']}/api/groups/23") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Post.new(uri.request_uri) request.basic_auth("admin", "smartvm") request.body = ' { "action" : "edit", "resource" : { "description" : "updated group description from ruby" } } ' response = http.request(request) puts JSON.pretty_generate(JSON.parse(response.body.strip))
Example 3: A GET using filtering with Ruby
#!/usr/bin/env ruby require 'json' require 'net/http' require 'openssl' require 'uri' expand_resources="expand=resources&attributes=description,miq_user_role_name" uri = URI.parse("https://#{ENV['MIQ']}/api/groups/?#{expand_resources}&filter[]=miq_user_role_name='*user*'") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Get.new(uri.request_uri) request.basic_auth("admin", "smartvm") response = http.request(request) puts "Reply:\n " + JSON.pretty_generate(JSON.parse(response.body.strip))
Example 3: Result
Result truncated and showing only the returned resources.
... "resources": [ { "description": "EvmGroup-user", "href": "https://192.0.2.0/api/groups/4", "id": "4", "miq_user_role_name": "EvmRole-user" }, { "description": "EvmGroup-vm_user", "href": "https://192.0.2.0/api/groups/9", "id": "9", "miq_user_role_name": "EvmRole-vm_user" }, { "description": "EvmGroup-user_self_service", "href": "https://192.0.2.0/api/groups/12", "id": "12", "miq_user_role_name": "EvmRole-user_self_service" }, { "description": "EvmGroup-user_limited_self_service", "href": "https://192.0.2.0/api/groups/13", "id": "13", "miq_user_role_name": "EvmRole-user_limited_self_service" } ], ...
Python
The same three examples shown above are illustrated here using Python.
The ManageIQ hostname or IP Address is being made available through the environment variable MIQ :
export MIQ="192.0.2.0"
Example 1: A simple GET with Python
Get the collection groups
#!/usr/bin/env python import requests import json import os url = 'https://' + str(os.environ["MIQ"]) + '/api/groups' response = requests.get(url, auth=('admin', 'smartvm'), verify=False) print("Result:\n" + json.dumps(json.loads(response.text), indent=4, sort_keys=True))
Example 2: Using POST to edit a group with Python
Edit an instance of the collection groups
#!/usr/bin/env python import requests import json import os url = 'https://' + str(os.environ["MIQ"]) + '/api/groups/23' request_body = { 'action': 'edit', 'resource' : { 'description' : 'updated group description from python' } } headers = {'Content-type': 'application/json'} response = requests.post(url, data=json.dumps(request_body), headers=headers, auth=('admin', 'smartvm'), verify=False) print("Result:\n" + json.dumps(json.loads(response.text), indent=4, sort_keys=True))
Example 3: A GET using filtering with Python
#!/usr/bin/env python import requests import json import os expand_resources="expand=resources&attributes=description,miq_user_role_name" url = "https://" + str(os.environ["MIQ"]) + "/api/groups/?" + str(expand_resources) + "&filter[]=miq_user_role_name='*user*'" response = requests.get(url, auth=('admin', 'smartvm'), verify=False) print("Result:\n" + json.dumps(json.loads(response.text), indent=4, sort_keys=True))
Example 3: Result
Result truncated and showing only the returned resources.
... "resources": [ { "description": "EvmGroup-user", "href": "https://192.0.2.0/api/groups/4", "id": "4", "miq_user_role_name": "EvmRole-user" }, { "description": "EvmGroup-vm_user", "href": "https://192.0.2.0/api/groups/9", "id": "9", "miq_user_role_name": "EvmRole-vm_user" }, { "description": "EvmGroup-user_self_service", "href": "https://192.0.2.0/api/groups/12", "id": "12", "miq_user_role_name": "EvmRole-user_self_service" }, { "description": "EvmGroup-user_limited_self_service", "href": "https://192.0.2.0/api/groups/13", "id": "13", "miq_user_role_name": "EvmRole-user_limited_self_service" } ], ...