Learning about REST APIs > REST API version and backward compatibility |  | next

# 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

Copyright © 2013-2016 Hewlett Packard Enterprise Development LP