HP OneView - Manual (Page 73)

5.6 REST API version and backward compatibility
When you perform a REST API operation, an X-API-Version header is required. This version
header corresponds to the REST API version of software currently running on the appliance. To
determine the correct REST API version, perform /rest/version. This GET operation does not
require an X-API-Version header. If multiple appliances are running in your environment, you
need to determine the REST API version required by each appliance.
The requests documented in the HP OneView 1.05 REST API scripting help correspond to a
versionNumber
of 4. Requests specifying API version 4 always provide the behavior documented
here. Future API changes will introduce higher version numbers.
Supported REST API versions
This release of HP OneView supports the new REST API version 4 in addition to supporting the
REST API version 3 (minimum) that was supported in previous releases of HP OneView.
The HP OneView REST API documentation for older REST API versions is available online at http://
www.hp.com/go/oneview/docs , and the documentation for the current version of supported REST
APIs is included with the online help for this release as well as online.
Backward compatibility
The following list explains how to preserve your existing scripts when upgrading to a new version
of HP OneView, take advantage of new functionality, and find the current and previous versions
of the HP OneView REST API documentation.
•
Prevent scripts from breaking
To prevent your existing scripts from breaking that were written for a specific API version, use
the same X-API-Version value for that specific REST API. This ensures that the same set of
data is sent and returned in the response body during PUT and POST operations.
NOTE: The set of possible enumerated values that may be returned in a given resource
attribute may be extended from release to release (independent of the API version). Clients
should ignore any values that they do not expect.
To maintain backward compatibility, the set of enumerated values will not be reduced and
the meaning of these values will not change for a given API version.
•
Use new functionality
To take advantage of new functionality, you must move to the new X-API-Version value.
If the X-API-Version value is set globally in your scripts, moving to a new X-API-Version
will likely impact multiple REST APIs. To view a list of REST APIs that have changed, see the
HP OneView Release Notes.
If you do not need to use the new functionality, you can use a previous X-API-Version and
avoid impacting your existing scripts. HP recommends that you move to the new
X-API-Version
, because backward compatibility is not guaranteed from release to release,
and older functionality will be deprecated.
The current version of the REST APIs are documented in the HP OneView REST API Reference
that is included on the appliance. To view previous versions of the REST API reference, go to
http://www.hp.com/go/oneview/docs .
5.7 Asynchronous versus synchronous operations
A synchronous task returns a response after the REST API operation. For example, POST
/rest/server-profiles
returns a newly created server profile in the response body. An
asynchronous task, such as creating an appliance backup returns the URI of a TaskResource
5.6 REST API version and backward compatibility 73