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>