8.3.3. Creating a Resource Asynchronously

Certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resources results in a 202 Accepted status. The initial document structure for a 202 Accepted resource also contains a creation_status element and link for creation status updates. For example:

POST /rhevm-api/{collection} HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<{resource}>
    <name>Resource-Name</name>
</{resource}>

HTTP/1.1 202 Accepted
Location: http://{host}/rhevm-api/{collection}/{resource_id}
Content-Type: application/xml

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    <name>Resource-Name</name>
    <creation_status>PENDING</creation status>
    <link rel="creation_status" 
      href="/rhevm-api/{collection}/{resource_id}/creation_status/{creation_status_id}"/>
      ...
</{resource}>

A GET request to the creation_status link provides a creation status update:

GET /rhevm-api/{collection}/{resource_id}/creation_status/{creation_status_id} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<creation id="{creation_status_id}"
  href="/rhevm-api/{collection}/{resource_id}/creation_status/{creation_status_id}">
    <status>COMPLETE</status>
</creation>

Overriding the asynchronous resource creation requires an Expect: 201-created header:

POST /rhevm-api/{collection} HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<{resource}>
    <name>Resource-Name</name>
</{resource}>