The API provides a set of services, each associated with a server path. For example, the service that manages the collection of virtual machines in the system is located in /vms, and the service that manages the virtual machine with identifier 123 is located in /vms/123.

In the Ruby software development kit, the root of that tree of services is implemented by the system service. It is retrieved by calling the system_service method of the connection:

Retrieving System Service
system_service = connection.system_service

Once you have the reference to the system service, you can use it to retrieve references to other services, using the *_service methods (called service locators).

For example, to retrieve a reference to the service that manages the collection of virtual machines in the system, you can use the vms_service service locator:

Retrieving Other Services
vms_service = system_service.vms_service

To retrieve a reference to the service that manages the virtual machine with identifier 123, use the service locator of the vm_service service. The service locator uses the virtual machine identifier as a parameter:

Retrieving Virtual Machine Service Using Identifier
vm_service = vms_service.vms_service('123')

The objects returned by the service locator calls are pure services, and do not contain data. For example, the vm_service Ruby object retrieved in the previous example is not the representation of a virtual machine. It is the service that is used to retrieve, update, delete, start, and stop a virtual machine.