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 or newer.

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://mymorpheus")
client.login("admin", "2dR[wpht~4!?>(Z~")

Verify SSL

Using HTTPS with an unverified SSL Certificate causes the CLI to error. This error can be supressed by configuring your client with verify_ssl: false to ignore SSL Certificate errors. Always be sure to point your client to a trusted and secure 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 appliance url and access token.

You can set your morpheus api environment variables like so:

export MORPHEUS_API_URL="https://mymorpheus"
export MORPHEUS_API_TOKEN="2003212e-0ee9-4ba9-ba45-abc8b05f9130"

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 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

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

When an API method does not succeed, an Exception will be raised.

Errors

The following errors can be encountered when invoking interface methods.

RestClient::Exception

This means the server returned something other than 200 OK, like 400 Bad Request, 401 Unauthorized, 403 Forbidden, or 500 Server Error.

You can can inspect the exception for more information about the error.

RestClient::Exceptions::Timeout

This means the API request took too long. The default timeout for most GET methods is 30 seconds.

You can use client.setopts(timeout:300) to work around this.

OpenSSL::SSL::SSLError

This indicates a bogus SSL certificate. You can configure your client with verify_ssl:false to resolve this.

Errno::ECONNREFUSED

This means the client url did not respond.

Errno::SocketError

This means the client url could not be communicated with.

List of API Interfaces

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

• account_groups
• account_users
• accounts
• activity
• appliance_settings
• approvals
• apps
• archive_buckets
• archive_files
• audit
• auth
• backup_jobs
• backup_restores
• backup_results
• backup_service_types
• backup_services
• backup_settings
• backups
• billing
• blueprints
• budgets
• catalog
• catalog_item_types
• certificate_types
• certificates
• clients
• cloud_datastores
• cloud_folders
• cloud_policies
• cloud_resource_pools
• clouds
• clusters
• containers
• credential_types
• credentials
• cypher
• dashboard
• datastores
• deploy
• deployments
• environments
• execute_schedules
• execution_request
• file_copy_request
• forgot
• group_policies
• groups
• guidance
• guidance_settings
• health
• image_builder
• instance_types
• instances
• integration_types
• integrations
• invoice_line_items
• invoices
• jobs
• key_pairs
• library_cluster_layouts
• library_cluster_packages
• library_container_scripts
• library_container_templates
• library_container_types
• library_container_upgrades
• library_instance_types
• library_layouts
• library_spec_template_types
• library_spec_templates
• license
• load_balancer_monitors
• load_balancer_pool_nodes
• load_balancer_pools
• load_balancer_pools_secondary
• load_balancer_profiles
• load_balancer_types
• load_balancer_virtual_servers
• load_balancers
• log_settings
• logs
• monitoring
• monitoring_settings
• network_dhcp_relays
• network_dhcp_servers
• network_domain_records
• network_domains
• network_edge_clusters
• network_floating_ips
• network_groups
• network_pool_ips
• network_pool_server_types
• network_pool_servers
• network_pools
• network_proxies
• network_routers
• network_security_server_types
• network_security_servers
• network_server_groups
• network_server_types
• network_servers
• network_services
• network_static_routes
• network_types
• networks
• old_cypher
• option_type_forms
• option_type_lists
• option_types
• options
• packages
• ping
• plugins
• policies
• power_schedules
• price_sets
• prices
• processes
• projects
• provision_types
• provisioning_license_types
• provisioning_licenses
• provisioning_settings
• reports
• resource_pool_groups
• roles
• scale_thresholds
• search
• security_group_rules
• security_groups
• security_package_types
• security_packages
• security_scans
• server_types
• servers
• service_plans
• setup
• snapshots
• storage_providers
• storage_server_types
• storage_servers
• storage_volume_types
• storage_volumes
• subnet_types
• subnets
• task_sets
• tasks
• usage
• user_groups
• user_settings
• user_sources
• users
• vdi
• vdi_allocations
• vdi_apps
• vdi_gateways
• vdi_pools
• virtual_images
• whitelabel_settings
• whoami
• wiki