ovirt-engine-sdk 4.0.1 → 4.4.1

data/README.adoc

@@ -1,4 +1,5 @@
 = oVirt Engine API Ruby SDK
+:reference: http://www.rubydoc.info/gems/ovirt-engine-sdk/OvirtSDK4
 
 == Introduction
 
@@ -11,67 +12,763 @@ just installed the gem then you will have everything already, but if you
 downloaded the source then you will need to generate it, follow the
 instructions in the `README.adoc` file of the parent directory.
 
+== Installation
+
+The SDK can be installed in Fedora 24 and CentOS 7 using the RPM packages
+provided by the oVirt project. To do so install the oVirt release package:
+
+  # dnf install http://resources.ovirt.org/pub/yum-repo/ovirt-release41.rpm
+
+Then install the SDK package:
+
+  # dnf install rubygem-ovirt-engine-sdk4
+
+For other operating systems (and also for Fedora and CentOS) you can
+install the SDK using the `gem` command, which will download the source
+from https://rubygems.org[RubyGems], build and install it:
+
+  $ gem install ovirt-engine-sdk
+
+The SDK uses http://www.xmlsoft.org[libxml2] for parsing and rendering
+XML and https://curl.haxx.se/libcurl[libcurl] for HTTP transfers. The
+parts of the SDK that interact with those libraries are written in C.
+This means that before building you must make sure you have the C
+compiler and the required header and libraries files installed in your
+system. For example, if you are using distributions like Fedora, or
+CentOS:
+
+  # dnf -y install \
+  gcc \
+  libcurl-devel \
+  libxml2-devel \
+  redhat-rpm-config \
+  ruby \
+  ruby-devel \
+  rubygems \
+  rubygems-devel
+
+NOTE: The installation of the `ruby`, `ruby-devel`, `rubygems` and
+`rubygems-devel` packages is necessary if you are going to use the Ruby
+version included in your distribution. If you are using tools like
+`rbenv` or `rvm` then this is not necessary.
+
+If you are using distributions like Debian, or Ubuntu:
+
+  # apt-get --assume-yes install \
+  gcc \
+  libcurl4-openssl-dev \
+  libxml2-dev \
+  ruby \
+  ruby-dev
+
+NOTE: The installation of the `ruby` and `ruby-dev` packages is
+necessary if you are going to use the Ruby version included in your
+distribution. If you are using tools like `rbenv` or `rvm` then this is
+not necessary.
+
+Some Linux distributions, like Debian and Ubuntu, provide multiple
+versions of `libcurl`, compiled with support for different TLS
+libraries: OpenSSL, NSS and GnuTLS. Currently the SDK only supports
+OpenSSL, so make sure that you have that version of `libcurl` installed.
+For example, in Ubuntu 16.04 if you have the NSS version installed, you
+will have to remove it and then install the OpenSSL version:
+
+  # apt-get --assume-yes remove libcurl4-nss-dev
+  # apt-get --assume-yes install libcurl4-openssl-dev
+
+NOTE: The examples above use the `dnf` command, which is the default in
+Fedora 24. In CentOS 7 you may need to use the `yum` command, as `dnf`
+is optional.
+
 == Usage
 
-To use the SDK require the `ovirtsdk4` file. That will give you
-access to all the classes of the SDK, and in particular to the
-{OvirtSDK4::Connection} class. This is the entry point of the SDK,
-and gives you access to the root of the tree of services of the API:
+=== Modules and classes
+
+All the classes of the SDK are inside the {reference}[OvirtSDK4] module.
+Within the module there are several kinds of classes:
+
+Connection::
+
+The {reference}/Connection[Connection] class, as is the mechanism to
+connect to the server and to get the reference to the root of the
+services tree.
+
+Errors::
+
+The {reference}/Error[Error] class is the base exception class that the
+SDK will raise when it needs to report any error.
++
+For certain kinds of errors there are specific error classes, extending
+the base error class:
++
+* {reference}/AuthError[AuthError] - Raised when authentication or
+authorization fail.
++
+* {reference}/ConnectionError[ConnectionError] - Raised when the name of
+the server can't be resolved, and when the server is down or
+unreachable.
++
+* {reference}/NotFoundError[NotFoundError] - Raised when the requested
+object doesn't exist.
++
+* {reference}/TimeoutError[TimeoutError] - Raised when an operation times
+out.
 
+Types::
+
+These classes implement the _types_ used by the API. For example, the
+{reference}/Vm[Vm] Ruby class is the implementation of the virtual
+machine type. These classes are just containers of data, they don't
+contain any logic.
++
+Instances of these classes are used as parameters and return values of
+_service methods_. The conversion to/from the underlying representation
+is handled transparently by the SDK.
+
+Services::
+
+These classes implement the _services_ supported by the API. For
+example, the {reference}/VmsService[VmsService] Ruby class is the
+implementation of the service that manages the collection of virtual
+machines of the system.
++
+Instances of these classes are automatically created by the SDK when a
+service is located. For example, a new instance of the `VmsService`
+class will be automatically created by the SDK when doing the following:
++
 [source,ruby]
 ----
-require 'ovirtsdk4'
+vms_service = connection.system_service.vms_service
+----
++
+Avoid creating instances of these classes manually, as the parameters of
+the constructors, and in general all the methods except the _service
+locators_ and _service methods_ (described later) may change in the
+future.
+
+There are other classes, like HTTP client classes, readers and writers.
+These are used to implement the HTTP communication, and for XML
+parsing and rendering. Refrain from using them, as they are internal
+implementation details that may change in the future: backwards
+compatibility isn't guaranteed.
+
+=== Connecting to the server
 
+To connect to the server require the `ovirtsdk4` file. That will give to
+the {reference}/Connection[Connection] class. This is the entry point of
+the SDK, and gives you access to the root of the tree of services of the
+API:
+
+[source,ruby]
+----
 # Create a connection to the server:
-connection = OvirtSDK4::Connection.new({
-  :url => 'https://engine.example.com/ovirt-engine/api',
-  :username => 'admin@internal',
-  :password => '...',
-  :ca_file => 'ca.pem',
-})
-
-# Get the reference to the system service:
+connection = OvirtSDK4::Connection.new(
+  url: 'https://engine.example.com/ovirt-engine/api',
+  username: 'admin@internal',
+  password: '...',
+  ca_file: 'ca.pem',
+)
+
+# Get the reference to the root of the tree of services:
 system_service = connection.system_service
+----
+
+The connection holds expensive resources, including a pool of HTTP
+connections to the server and an authentication token. It is very
+important to free these resources when they are no longer in use:
 
-# Always remember to close the connection when finished:
+[source,ruby]
+----
+# Close the connection to the server:
 connection.close
 ----
 
+The connection and all the services that have been obtained from it
+can't be used after the connection has been closed.
+
 The `ca.pem` file is required when connecting to a server protected
 with TLS. In an usual oVirt installation it will be in
 `/etc/pki/ovirt-engine/ca.pem`. If you don't specify `ca_file`, then
-the system wide CA certificate store will be used.
+system wide CA certificate store will be used.
+
+If something fails when trying to create the connection (authentication
+failure, communication failure, etc) the SDK will raise a
+{reference}/Error[Error] exception containing the details.
+
+=== Using _types_
+
+The type classes are pure data containers, they don't have any logic or
+operations. Instances can be created and modified at will.
+
+Creating or modifying one of this instances does *not* have any effect
+in the server side, unless they are explicitly passed to a call to one
+of the service methods described below. Changes in the server side are
+*not* automatically reflected in the instances that already exist in
+memory.
+
+The constructors of these classes have multiple optional arguments, one
+for each attribute of the type. This is intended to simplify creation of
+objects using nested calls to multiple constructors. For example, to
+create an instance of a virtual machine, with an specification of the
+cluster and template that it should use, and the memory it should have:
+
+[source,ruby]
+----
+vm = OvirtSDK4::Vm.new(
+  name: 'myvm',
+  cluster: OvirtSDK4::Cluster.new(
+    name: 'mycluster'
+  ),
+  template: OvirtSDK4::Template.new(
+    name: 'mytemplate'
+  ),
+  memory: 1073741824
+)
+----
+
+The hashes passed to these constructors are processed recursively. For
+example, in the above code instead of explicitly calling the constructor
+for the `Cluster` and `Template` classes it is also possible to use
+plain hashes:
+
+[source,ruby]
+----
+vm = OvirtSDK4::Vm.new(
+  name: 'myvm',
+  cluster: {
+    name: 'mycluster'
+  },
+  template: {
+    name: 'mytemplate'
+  },
+  memory: 1073741824
+)
+----
+
+The SDK will internally convert those hashes to the required classes, so
+the result will be exactly the same.
+
+Using the constructors in this way is recommended, but not mandatory.
+You can also create the instance with no arguments in the call to the
+constructor, and then populate the object step by step, using the
+setters, or using a mix of both approaches:
+
+[source,ruby]
+----
+vm = OvirtSDK4::Vm.new
+vm.name = 'myvm'
+vm.cluster = OvirtSDK4::Cluster.new(name: 'mycluster')
+vm.template = OvirtSDK4::Template.new(name: 'mytemplate')
+vm.memory = 1073741824
+----
+
+Attributes that are defined as lists of objects in the specification of
+the API are implemented as Ruby arrays. For example, the
+`custom_properties` attributes of the
+http://ovirt.github.io/ovirt-engine-api-model/master/#types/vm[Vm] type
+is defined as a list of objects of type `CustomProperty`, so when using
+it in the SDK it will be a Ruby array:
+
+[source,ruby]
+----
+vm = OvirtSDK4::Vm.new(
+  name: 'myvm',
+  custom_properties: [
+    OvirtSDK4::CustomProperty.new(...),
+    OvirtSDK4::CustomProperty.new(...),
+    ...
+  ]
+)
+----
+
+Attributes that are defined as enumerated values in the specification of
+the API are implemented as constatns within a module that has the same
+name than the enumerated type. For example, the `status` attribute of
+the `Vm` type is defined using the
+http://ovirt.github.io/ovirt-engine-api-model/master/#types/vm_status[VmStatus]
+enum:
+
+[source,ruby]
+----
+case vm.status
+when OvirtSDK4::VmStatus::DOWN
+  ...
+when OvirtSDK4::VmStatus::IMAGE_LOCKED
+  ...
+end
+----
+
+NOTE: In the specification of the API the values of enum types appear in
+lower case, because that is what is used in the XML or JSON documents,
+but in Ruby it is common practice to use upper case for this kind of
+constants, so that is how they are defined in the Ruby SDK: all upper
+case.
+
+Reading the attributes of instances of types is done using the
+corresponding attribute readers:
+
+[source,ruby]
+----
+puts "vm.name: #{vm.name}"
+puts "vm.memory: #{vm.memory}"
+vm.custom_properties.each do |custom_property|
+  ...
+end
+----
+
+=== Using _links_
+
+Some of the attributes of types are defined as _links_ in the
+specification of the API. This is done to indicate that their value
+won't usually be populated when retrieving the representation of that
+object, only a link will be returned instead. For example, when
+retrieving a virtual machine, the XML returned by the server will look
+like this:
+
+[source,xml]
+----
+<vm id="123" href="/ovirt-engine/api/vms/123">
+  <name>myvm</name>
+  <link rel="diskattachments" href="/ovirt-engine/api/vms/123/diskattachments/>
+  ...
+</vm>
+----
+
+That link is available as `vm.disk_attachments`, but it doesn't contain
+the actual disk attachments. To get the actual data the
+{reference}/Connection[Connection] class provides a
+{reference}/Connection#follow_link-instance_method[follow_link] method
+that uses the value of the `href` XML attribute to retrieve the actual
+data. For example, to retrieve the details of the disks of the virtual
+machine, you can first follow the link to the disk attachments, and then
+follow the link to each of the disks:
+
+[source,ruby]
+----
+# Retrieve the virtual machine:
+vm = vm_service.get
+
+# Follow the link to the disk attachments, and then to the disks:
+attachments = connection.follow_link(vm.disk_attachments)
+attachments.each do |attachment|
+  disk = connection.follow_link(attachment.disk)
+  puts "disk.alias: #{disk.alias}"
+end
+----
+
+=== Locating services
+
+The API provides a set of _services_, each associated to a particular
+path within the URL space of the server. For example, the service that
+manages the collection of virtual machines of the system lives in
+`/vms`, and the service that manages the virtual machine with identifier
+`123` lives in `/vms/123`.
 
-Once you have the reference to the system service you can use it to get
-references to other services, and call their methods. For example, to
-retrieve the list of virtual machines of the system you can use the
-`vms_service` method, which returns a reference to the service that
-manages the virtual machines:
+In the SDK the root of that tree of services is implemented by the
+_system service_. It is obtained calling the
+{reference}/Connection#system_service-instance_method[system_service]
+method of the connection:
+
+[source,ruby]
+----
+system_service = connection.system_service
+----
+
+Once you have the reference to this system service you can use it to get
+references to other services, calling the `+*_service+` methods (called
+_service locators_) of the previous service. For example, to get a
+reference to the service that manages the collection of virtual machines
+of the system use the
+{reference}/SystemService#vms_service-instance_method[vms_service]
+service locator:
 
 [source,ruby]
 ----
-# Get the reference to the "vms" service:
 vms_service = system_service.vms_service
 ----
 
-This service is an instance of {OvirtSDK4::VmsService}, and it has
-a `list` method that returns an array of virtual machines, which are
-instances of the {OvirtSDK4::Vm} class:
+To get a reference to the service that manages the virtual machine with
+identifier `123`, use the
+{reference}/VmsService#vm_service-instance_method[vm_service] service
+locator of the service that manages the collection of virtual machines.
+It receives as a parameter the identifier of the virtual machine:
 
 [source,ruby]
 ----
-# Retrieve the virtual machines:
+vm_service = vms_service.vms_service('123')
+----
+
+IMPORTANT: Calling the service locators doesn't send any request to the
+server. The Ruby objects that they return are pure services, they
+don't contain any data. For example, the `vm_service` Ruby object
+obtained in the previous example is *not* the representation of a
+virtual machine. It is the service that can be used to retrieve, update,
+delete, start and stop that virtual machine.
+
+=== Using services
+
+Once you have located the service you are interested on, you can start
+calling its _service methods_, the methods that send requests to the
+server and do the real work.
+
+The services that manage collections of object usually have the `list`
+and `add` methods.
+
+The services that manage a single object usually have the `get`,
+`update` and `remove` methods.
+
+Both kinds of services can also have additional _action methods_, which
+perform actions other than retrieving, creating, updating or removing.
+Most frequently they are available in services that manage a single
+object.
+
+==== Using the _get_ methods
+
+These service methods are used to retrieve the representation of a
+single object. For example, to retrieve the representation of the
+virtual machine with identifier `123`:
+
+[source,ruby]
+----
+# Find the service that manages the virtual machine:
+vms_service = system_service.vms_service
+vm_service = vms_service.vm_service('123')
+
+# Retrieve the representation of the virtual machine:
+vm = vm_service.get
+----
+
+The result will be an instance of the corresponding type. For example,
+in this case, the result will be an instance of the Ruby class
+{reference}/Vm[Vm].
+
+The `get` methods of some services support additional parameters that
+control how to retrieve the representation of the object, or what
+representation to retrieve in case there are multiple representations.
+For example, for virtual machines you may want to retrieve its current
+state, or the state that will be used the next time it is started, as
+they may be different. To do so the `get` method of the service that
+manages a virtual machine supports a
+http://ovirt.github.io/ovirt-engine-api-model/master/#services/vm/methods/get/parameters/next_run[next_run]
+boolean parameter:
+
+[source,ruby]
+----
+# Retrieve the representation of the virtual machine, not the
+# current one, but the one that will be used after the next
+# boot:
+vm = vm_service.get(next_run: true)
+----
+
+Check the {reference}[reference] documentation of the SDK to find out
+the details.
+
+If the object can't be retrieved, for whatever reason, the SDK will
+raise an {reference}/Error[Error] exception, containing the details of
+the failure. This includes the situation when the object doesn't
+actually exist. Note that the exception will be raised when calling the
+`get` service method, the call to the service locator method never
+fails, even if the object doesn't exist, because it doesn't send any
+request to the server. For example:
+
+[source,ruby]
+----
+# Find the service that manages a virtual machine that does
+# not exist. This will succeed.
+vm_service = vms_service.vm_service('junk')
+
+# Retrieve the virtual machine. This will raise an exception.
+vm = vm_service.get
+----
+
+==== Using the _list_ methods
+
+These service methods are used to retrieve the representations of the
+objects of the collection. For example, to retrieve the complete
+collection of virtual machines of the system:
+
+[source,ruby]
+----
+# Find the service that manages the collection of virtual
+# machines:
+vms_service = system_service.vms_service
 vms = vms_service.list
+----
+
+The result will be a Ruby array containing the instances of the
+corresponding types. For example, in this case, the result will be a
+list of instances of the Ruby class {reference}/Vm[Vm].
+
+The `list` methods of some services support additional parameters. For
+example, almost all the top level collections support a `search`
+parameter that can be used ask the server to filter the results, and a
+`max` parameter that can be used to limit the number of results returned
+by the server. For example, to get the list of virtual machines whose
+name starts with `my`, and to get at most 10 results:
+
+[source,ruby]
+----
+vms = vms_service.list(search: 'name=my*', max: 10)
+----
 
-# Print the names and identifiers of the virtual machines:
-vms.each do |vm|
-  puts "#{vm.name}: #{vm.id}"
+NOTE: Not all the `list` methods support these parameters, and some
+`list` methods may support other additional parameters. Check the
+{reference}[reference] documentation of the SDK to find out the details.
+
+If list of results is empty, for whatever reason, the returned value
+will be an empty Ruby array, it will never be `nil`.
+
+If there is an error while trying to retrieve the result, then the SDK
+will raise an {reference}/Error[Error] exception containing the details
+of the failure.
+
+==== Using the _add_ methods
+
+These service methods add new elements to collections. They receive an
+instance of the relevant type describing the object to add, send the
+request to add it, and return an instance of the type describing the
+added object.
+
+For example, to add a new virtual machine named `myvm`:
+
+[source,ruby]
+----
+# Add the virtual machine:
+vm = vms_service.add(
+  OvirtSDK4::Vm.new(
+    name: 'myvm',
+    cluster: {
+      name: 'mycluster'
+    },
+    template: {
+      name: 'mytemplate'
+    }
+  )
+)
+----
+
+If the object can't be created, for whatever reason, the SDK will
+raise an {reference}/Error[Error] exception containing the details of
+the failure. It will never return `nil`.
+
+It is very important to understand that the Ruby object returned by this
+`add` method is an instance of the relevant type, it isn't a service,
+just a container of data. In this particular example the returned object
+will be an instance of the {reference}/Vm[Vm] class. If once the
+virtual machine is created you need to perform some operation on it,
+like retrieving it again, or starting it, you will first need to find
+the service that manages it, calling the corresponding service locator:
+
+[source,ruby]
+----
+# Add the virtual machine:
+vm = vms_service.add(
+  ...
+)
+
+# Find the service that manages the virtual machine:
+vm_service = vms_service.vm_service(vm.id)
+
+# Perform some other operation on the virtual machine, like
+# starting it:
+vm_service.start
+----
+
+Note that the creation of most objects is an asynchronous task. That
+means, for example, that when creating a new virtual machine the `add`
+method will return *before* the virtual machine is completely created
+and ready to be used. It is good practice to poll the status of the
+object till it is completely created. For a virtual machine that means
+checking till the status is _down_. So the recommended approach to create
+a virtual machine is the following:
+
+[source,ruby]
+----
+# Add the virtual machine:
+vm = vms_service.add(
+  ...
+)
+
+# Find the service that manages the virtual machine:
+vm_service = vms_service.vm_service(vm.id)
+
+# Wait till the virtual machine is down, which indicats that all the
+# disks have been created:
+loop do
+  sleep(5)
+  vm = vm_service.get
+  break if vm.status == OvirtSDK4::VmStatus::DOWN
 end
 ----
 
-You will find more usage examples in the `examples` directory.
+In the above loop it is very important to retrieve the object each time,
+using the `get` method, otherwise the `status` attribute won't be
+updated.
+
+==== Using the _update_ methods
+
+These service methods update existing objects. They receive an instance
+of the relevant type describing the update to perform, send the request
+to update it, and return an instance of the type describing the updated
+object.
+
+For example, to update the name of a virtual machine from `myvm` to
+`newvm`:
+
+[source,ruby]
+----
+# Find the virtual machine, and then the service that
+# manages it:
+vm = vms_service.list(search: 'name=myvm').first
+vm_service = vms_service.vm_service(vm.id)
+
+# Update the name:
+updated_vm = vms_service.update(
+  OvirtSDK4::Vm.new(
+    name: 'newvm'
+  )
+)
+----
+
+When performing updates, try to avoid sending the complete
+representation of the object, send only the attributes that you want to
+update. For example, try to *avoid* this:
+
+[source,ruby]
+----
+# Retrieve the current representation:
+vm = vm_service.get
+
+# Update the representation, in memory, no request sent
+# to the server:
+vm.name = 'newvm'
+
+# Send the update. Do *not* do this.
+vms_service.update(vm)
+----
+
+The problem with that is double. First you are sending much more
+information than what the server needs, thus wasting resources. Second,
+and more important, the server will try to update all the attributes of
+the object, even those that you didn't need to change. Usually that
+isn't a problem, but has caused many unexpected bugs in the server side
+in the past.
+
+The `update` methods of some services support additional parameters that
+control how or what to update. For example, for virtual machines you may
+want to update its current state, or the state that will be used the
+next time it is started. To do so the `update` method of the service
+that manages a virtual machine supports a
+http://ovirt.github.io/ovirt-engine-api-model/master/#services/vm/methods/update/parameters/next_run[next_run]
+boolean parameter:
+
+[source,ruby]
+----
+# Update the memory of the virtual machine 1 GiB, but not the current
+# one, the one it will have after the next boot:
+vm = vm_service.update(
+  OvirtSDK4::Vm.new(
+    memory: 1073741824
+  ),
+  next_run: true
+)
+----
+
+If the update can't be performed, for whatever reason, the SDK will
+raise an {reference}/Error[Error] exception containing the details of
+the failure. It will never return `nil`.
+
+The Ruby object returned by this `update` method is an instance of the
+relevant type, it isn't a service, just a container of data. In this
+particular example the returned object will be an instance of the
+{reference}/Vm[Vm] class.
+
+==== Using the _remove_ methods
+
+These service methods remove existing objects. They usually don't
+receive any parameters, as they are methods of the services that manage
+single objects, therefore the service already knows what object to
+remove.
+
+For example, to remove the virtual machine with identifier `123`:
+
+[source,ruby]
+----
+# Find the service that manages the virtual machine:
+vm_service = vms_service.vm_service('123')
+
+# Remove the virtual machine:
+vms_service.remove
+----
+
+The `remove` methods of some services support additional parameters that
+control how or what to remove. For example, for virtual machines it is
+possible to remove the virtual machine while preserving the disks.
+To do so the `remove` method of the service that manages a virtual machine supports a
+http://ovirt.github.io/ovirt-engine-api-model/master/#services/vm/methods/remove[detach_only]
+boolean parameter:
+
+[source,ruby]
+----
+# Remove the virtual machine, but preserve the disks:
+vm_service.remove(detach_only: true)
+----
+
+The `remove` methods return `nil` if the object is removed successfully.
+It does *not* return the removed object. If the object can't be removed,
+for whatever reason, the SDK will raise an {reference}/Vm[Vm]
+exception containing the details of the failure.
+
+==== Using _action_ methods
+
+These service methods perform miscellaneous operations. For example, the
+service that manages a virtual machine has methods to start and stop it:
+
+[source,ruby]
+----
+# Start the virtual machine:
+vm_service.start
+----
+
+Many of these methods include parameters that modify the operation. For
+example, the method that starts a virtual machine supports a
+http://ovirt.github.io/ovirt-engine-api-model/master/#services/vm/methods/start/parameters/use_cloud_init[use_cloud_init]
+parameter that indicates if you want to start it using
+https://cloudinit.readthedocs.io/cloud-init[cloud-init]:
+
+[source,ruby]
+----
+# Start the virtual machine:
+vm_service.start(cloud_init: true)
+----
+
+Most action methods return `nil` when they succeed, and raise a
+{reference}/Error[Error] when they fail. But a few action methods return
+values. For example, the service that manages a storage domains has an
+http://ovirt.github.io/ovirt-engine-api-model/master/#services/storage_domain/methods/is_attachedd[is_attached]
+action method that checks if the storage domain is already attached to a
+data center. That method returns a boolean:
+
+[source,ruby]
+----
+# Check if the storage domain is attached to a data center:
+sds_service = system_service.storage_domains_service
+sd_service = sds_service.storage_domain_service('123')
+if sd_service.is_attached
+  ...
+end
+----
+
+Check the {reference}[reference] documentation of the SDK to see the
+action methods supported by each service, the parameters that they
+support, and the values that they return.
+
+== More information
+
+The reference documentation of the API is available
+http://ovirt.github.io/ovirt-engine-api-model[here].
 
-== Reference
+The reference documentation of the SDK is available {reference}[here].
 
-The reference documentation is available
-http://www.rubydoc.info/gems/ovirt-engine-sdk[here].
+There is a collection of examples that show how to use the SDK
+https://github.com/oVirt/ovirt-engine-sdk-ruby/tree/master/sdk/examples[here].