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 current REST API version on a given appliance, perform GET /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.


	NOTE: If an `X-API-Version` header is not included in the request, the APIs default to version 1. Since most APIs in HPE OneView have a minimum of 3 or greater, invoking an API without including the `X-API-Version` header will likely result in an HTTP 404 error, because that version of the API will not be found.

The requests documented in the HPE OneView REST API Scripting Help correspond to the API Reference version included in the product.

Supported REST API versions

This release of HPE OneView supports the latest REST API version in addition to supporting the REST API versions supported in previous releases of HPE OneView.

Backward compatibility

The following list explains how to preserve your existing scripts when upgrading to a new version of HPE OneView, take advantage of new functionality, and find the current and previous versions of the HPE 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.


	NOTE: The Index or SCMB always returns the latest version of resource data, independent of what is sent in the `X-API-Version` header on the request (this header controls the Index DTO model, but not the data contained within). To obtain a specific version of a resource’s data, perform a `GET` on the resource’s URI with the desired `X-API-Version` header.

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 "What's New?" page in the HPE OneView API Reference.

If you do not need to use the new functionality, you can use a previous X-API-Version and avoid impacting your existing scripts. Hewlett Packard Enterprise 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 HPE OneView API Reference that is included on the appliance. To view previous versions of the reference, go to www.hpe.com/info/oneview/docs.

prev	up	next
Asynchronous versus synchronous operations	home	Return codes