nova/doc/source/v2/2.0_general_info.rst

General Compute API v2.0 information

The OpenStack Compute API is defined as a ReSTful HTTP service. The API takes advantage of all aspects of the HTTP protocol (methods, URIs, media types, response codes, etc.) and providers are free to use existing features of the protocol such as caching, persistent connections, and content compression among others. For example, providers who employ a caching layer may respond with a 203 when a request is served from the cache instead of a 200. Additionally, providers may offer support for conditional GET requests using ETags, or they may send a redirect in response to a GET request. Clients should be written to account for these differences.

Providers can return information identifying requests in HTTP response headers, for example, to facilitate communication between the provider and client users.

OpenStack Compute is a compute service that provides server capacity in the cloud. Compute Servers come in different flavors of memory, cores, disk space, and CPU, and can be provisioned in minutes. Interactions with Compute Servers can happen programmatically with the OpenStack Compute API.

We welcome feedback, comments, and bug reports at bugs.launchpad.net/nova.

Intended audience

This guide assists software developers who want to develop applications using the OpenStack Compute API. To use this information, you should have access to an account from an OpenStack Compute provider, and you should also be familiar with the following concepts:

• OpenStack Compute service
• ReSTful web services
• HTTP/1.1
• JSON data serialization formats

Concepts

To use the OpenStack Compute API effectively, you should understand several key concepts:

• Server

  A virtual machine (VM) instance in the compute system. Flavor and image are requisite elements when creating a server.

• Flavor

  An available hardware configuration for a server. Each flavor has a unique combination of disk space, memory capacity and priority for CPU time.

• Image

  A collection of files used to create or rebuild a server. Operators provide a number of pre-built OS images by default. You may also create custom images from cloud servers you have launched. These custom images are useful for backup purposes or for producing “gold” server images if you plan to deploy a particular server configuration frequently.

• Reboot

  Use this function to perform either a soft or hard reboot of a server. With a soft reboot, the operating system is signaled to restart, which allows for a graceful shutdown of all processes. A hard reboot is the equivalent of power cycling the server. The virtualization platform should ensure that the reboot action has completed successfully even in cases in which the underlying domain/VM is paused or halted/stopped.

• Rebuild

  Use this function to remove all data on the server and replaces it with the specified image. Server ID and IP addresses remain the same.

• Resize

  Use this function to convert an existing server to a different flavor, in essence, scaling the server up or down. The original server is saved for a period of time to allow rollback if there is a problem. All resizes should be tested and explicitly confirmed, at which time the original server is removed. All resizes are automatically confirmed after 24 hours if you do not confirm or revert them.

• Pause

  You can pause a server by making a pause request. This request stores the state of the VM in RAM. A paused instance continues to run in a frozen state.

• Suspend

  Administrative users might want to suspend an instance if it is infrequently used or to perform system maintenance. When you suspend an instance, its VM state is stored on disk, all memory is written to disk, and the virtual machine is stopped. Suspending an instance is similar to placing a device in hibernation; memory and vCPUs become available to create other instances.

Reference

For a reference listing for the Compute API v2, see the *Compute API v2 reference (CURRENT)*.

For information about Compute API v 2 extensions, see the *Compute API v2 extensions (CURRENT)*.