APIClient

APIClient

The Morpheus CLI gem provides the APIClient class for use in your own ruby code.

This guide is written for use with the latest morpheus-cli version 4.1.2.

Authentication

APIClient can be used with either a username and password or an access token.

Client with Username and Pasword

Instantiate a new APIClient and login with a username and password.

require 'morpheus/api'
client = Morpheus::APIClient.new(url:"https://morpheus.yourcompany.com", verify_ssl: false)
client.login("admin", "your-morpheus-password")

Setting verify_ssl: false is needed to ignore SSL Certificate errors. It should only be used with the a trusted remote Morpheus appliance url.

Client With Access Token

Instantiate a new APIClient with an access token.

require 'morpheus/api'
client = Morpheus::APIClient.new(url:ENV['MORPHEUS_API_URL'], access_token: ENV['MORPHEUS_API_TOKEN'], verify_ssl: false)

This example uses environment variables to read the your morpheus url and token.

You can set your morpheus api environment variables like so:

export MORPHEUS_API_URL="https://morpheus.yourcompany.com"
export MORPHEUS_API_TOKEN="your-morpheus-access-token"

Refresh Access Token

Refresh your access token. This can only be done after logging in with a username and password, or instantiating an APIClient with a valid refresh_token, you can refresh the token for your user as follows:

WARNING: This will invalidate your current access token, so make sure it is no longer in use before doing this.

client.refresh_token()

Example Usage

After authenticating, you can interact with the API by invoking the interface methods. The paradigm is client.interface.method(params).

Whoami

Fetch details about yourself, the current user.

results = client.whoami.get()
puts "Hello #{results['user']['username']}"

List Instances

Fetch a list of instances.

results = client.instances.list()

Get Instance By ID

Fetch a specific instance by ID.

instance = client.instances.get(5)

Find an App By Name

Fetch a list of apps, filtered by an exact match on name.

results = client.apps.list({name:"Test App"})

Search for Apps

Fetch a list of apps, filtered by phrase to match any part of the app name.

results = client.apps.list({phrase:"dev"})

List All Users

Fetch a list of all users. Print their usernames.

The first argument for the users interface methods is account_id. Passing nil indicates to use your own account.

results = client.users.list(nil, {max:10000,sort:"username"})
users = results['users']
puts "Morpheus Users (#{users.size})", "==================", users.collect {|u| "#{u['username']} | #{u['firstName']} #{u['lastName']}" }.join("\n")

Get Count of Clouds

Fetch a list of all users. Print their usernames.

The first argument for the users interface methods is account_id. Passing nil indicates to use your own account.

results = client.clouds.list()
puts "#{results['meta']['total']} clouds"

The results from the list methods typically return a meta object that contains the total count that was found and other info about the results returned.

Create Instance

Create an instance, payload needs to be filled in.

# payload parameters abbreviated
payload = {"instance": {"name":"api test"},"zoneId":1}
results = client.instances.create(payload)

Result Format

When invoking interface methods, the return value is a Hash containing the JSON response from the Morpheus API.

This is true when the API returns 200 OK, otherwise an exception is raised. See Error Handling.

Error Handling

If an API method does not return 200 OK, a RestClient Exception will be raised containing details about the HTTP Error Code, etc.

If the server itself is unreachable, Errno::ECONNREFUSED or SocketError will raised.

List of API Interfaces

APIClient provides the following interfaces, each with their own list of methods:

• account_groups
• accounts
• apps
• archive_buckets
• archive_files
• auth
• blueprints
• cloud_datastores
• cloud_folders
• cloud_policies
• cloud_resource_pools
• clouds
• clusters
• containers
• custom_instance_types
• cypher
• dashboard
• deploy
• deployments
• environments
• execute
• execute_schedules
• execution_request
• file_copy_request
• group_policies
• groups
• image_builder
• instance_types
• instances
• key_pairs
• library_compute_type_layouts
• library_container_scripts
• library_container_templates
• library_container_types
• library_container_upgrades
• library_instance_types
• library_layouts
• license
• load_balancers
• logs
• monitoring
• monitoring.checks
• monitoring.groups
• monitoring.apps
• monitoring.incidents
• monitoring.alerts
• monitoring.contacts
• network_domain_records
• network_domains
• network_groups
• network_pool_ips
• network_pool_servers
• network_pools
• network_proxies
• network_services
• network_subnet_types
• network_subnets
• network_types
• networks
• option_type_lists
• option_types
• policies
• power_schedules
• processes
• provision_types
• refresh_token
• reports
• roles
• security_group_rules
• security_groups
• server_types
• servers
• service_plans
• setup
• storage_providers
• task_sets
• tasks
• user_groups
• user_settings
• user_sources
• users
• virtual_images
• whoami
• wiki