HP OneView - Manual (Page 73)

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 X-API-Version header 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-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
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