7.2.4.  Creating a Resource in a Collection

The API creates a new resource with a POST request to the collection URI containing a representation of the new resource.
A POST request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request.
Each resource type has its own specific required properties. The client supplies these properties as XML elements when creating a new resource. Refer to the individual resource type documentation for more details. If a required property is absent, the creation fails with a fault representation indicating the missing elements.
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

HTTP/1.1 201 Created
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    ...
</resource>
The Location header in the response gives the URI of the queried resource. The response body contains either a complete representation, partial representation or no representation of the resource. It is recommended that clients rely only on fetching the representation via the URI in the response header.

7.2.4.1.  Asynchronous Requests

The API performs asynchronous POST requests unless the user overrides them with a Expect: 201-created header.
For example, certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resource 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 /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

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

HTTP/1.1 202 Accepted
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>
A GET request to the creation_status link provides a creation status update:
GET /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="/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>
Overriding the asynchronous resource creation requires an Expect: 201-created header:
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

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