ine.api.model.4.2.0.source-code.001-Introduction.adoc Maven / Gradle / Ivy

Go to download
== Introduction

The {engine-name} provides a *Representational State Transfer (REST)
API*. The API provides software developers and system administrators
with control over their {product-name} environment outside of the
standard web interface. The API is useful for developers and
administrators to integrate the functionality of a
{product-name} environment with custom scripts or external applications
that access the API via the standard Hypertext Transfer Protocol (HTTP).

The benefits of the API are:

* Broad client support - Any programming language, framework, or
system with support for HTTP protocol can use the API.

* Self descriptive - Client applications require minimal knowledge of
the virtualization infrastructure, as many details are discovered at
runtime.

* Resource-based model - The resource-based REST model provides a
natural way to manage a virtualization platform.

This provides developers and administrators with the ability to:

* Integrate with enterprise IT systems.

* Integrate with third-party virtualization software.

* Perform automated maintenance or error-checking tasks.

* Automate repetitive tasks in a {product-name} environment with
scripts.

This documentation acts as a reference for the {product-name} API. It
aims to provide developers and administrators with instructions and
examples to help harness the functionality of their {product-name}
environment through the API, either directly or using the provided SDKs.

=== Representational State Transfer

*Representational State Transfer (REST)* is a design architecture that
focuses on resources for a specific service and their representations. A
resource representation is a key abstraction of information that
corresponds to one specific managed element on a server. A client sends
a request to a server element located at a Uniform Resource Identifier
(URI) and performs operations with standard HTTP methods, such as `GET`,
`POST`, `PUT`, and `DELETE`. This provides a stateless communication
between the client and server where each request acts independently of any
other request, and contains all the information necessary to complete the
request.

=== API Prerequisites

Prerequisites for using the {product-name} API:

* A networked installation of {engine-name}, which includes the API.

* A client or programming library that initiates and receives HTTP requests
from the API server. For example:

** The https://github.com/oVirt/ovirt-engine-sdk/tree/master/sdk[oVirt Python SDK].

** The https://github.com/oVirt/ovirt-engine-sdk-ruby/tree/master/sdk[oVirt Ruby SDK].

** The https://github.com/oVirt/ovirt-engine-sdk-java/tree/master/sdk[oVirt Java SDK].

** The https://curl.haxx.se[cURL] command line tool.

** https://addons.mozilla.org/en-US/firefox/addon/restclient[RESTClient], a
debugger for RESTful web services.

* Knowledge of Hypertext Transfer Protocol (HTTP), the protocol
used for REST API interactions. The Internet Engineering Task Force provides
a Request for Comments (RFC) explaining the Hypertext Transfer Protocol
at http://www.ietf.org/rfc/rfc2616.txt.

* Knowledge of Extensible Markup Language (XML) or JavaScript Object
Notation (JSON), which the API uses to construct resource representations.
The W3C provides a full specification on XML at http://www.w3.org/TR/xml.
ECMA International provide a free publication on JSON at
http://www.ecma-international.org.