determine the correct REST API version, perform /rest/version. This GET operation does not require an X-API-Versionheader. If multiple appliances are running in your environment, you need to determine the REST API version required by each appliance.

The X-API-Versionheader for this release of HP OneView must always be 3 (X-API-Version:3).

5.7 Asynchronous versus synchronous operations

A synchronous task returns a response after the REST API operation. For example, POST /rest/server-profilesreturns a newly created server profile in the response body. An asynchronous task, such as creating an appliance backup returns the URI of a TaskResource resource model. You can use the TaskResource resource model URI to list the current status of the operation.

5.8 Task resource

When you make an asynchronous REST API operation, HTTP status 202 Accepted is returned and the URI of a TaskResource resource model is returned in the Location header of the response.

You can then perform a GET on the TaskResource model URI to poll for the status of the asynchronous operation. The TaskResource model also contains the name and URI of the resource that is affected by the task in the associatedResource attribute.

Creating an appliance backup example

1.Create an appliance backup.

/rest/backups

The URI of a TaskResource in the Location header is returned in the response.

2.Poll for status of the backup using the TaskResource URI returned in step 1.

/rest/tasks/{id}

3.When the task reaches the Completed state, use the associatedResource URI in the TaskResource to download the backup file.

GET {associatedResource URI}

5.9 Error handling

If an error occurs during a REST API operation, a 4xx (client-side) or 5xx (appliance) error is returned along with an error message (ErrorMessage resource model). The error message contains a description and might contain recommended actions to correct the error.

A successful REST API POST operation returns the newly created resource (synchronous) or a TaskResource URI in the Location header (asynchronous).

5.10 Concurrency control using etags

A client uses etags to verify the version of the resource model. This prevents the client from modifying (PUT) a version of the resource model that is not current. For example, if a client performs a GET on a server profile and receives an etag in the response header, modifies the server profile, and then updates (PUT) the resource model, the etag in the PUT request header must match the resource model etag. If the etags do not match, the client PUT request will not complete and a 412 PRECONDITION FAILED error is returned.

5.7 Asynchronous versus synchronous operations 73