Share this page
POST: Create instances in a collection
This topic provides instructions for using the POST operation to create entities.
Overview
To create an instance, perform a POST on the collection, passing a JSON string that contains at least the required fields.
To create an instance:
-
Use the fields metadata resource, which returns the fields available for the entity/resource.
Note: The data returned for an instance may contain calculated fields that cannot be POSTed or PUT.
-
Create a string that has data for all the required fields and any additional fields you want to initialize. The JSON input must be in the same format returned by a GET operation on members of the collection.
-
POST the data to the collection.
-
On success, the HTTP return value is 201. The returned string is the complete data of the new instance. The new instance has the default values for any field not specified in the POST input. The Location header contains the URI of the created instance.
On failure, a status code and error message are returned.
Examples
Example: POST request for defects
-
Request: Data array of entity objects to create.
-
Response: Data array of entity objects created successfully, each object contains an ID.
*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects
{
"data": [{
"parent": {
"type": "work_item_root",
"id": "1001"
},
"release": {
"type": "release",
"id": "1002"
},
"description": "When advancing to last page in catalog, an error occurs. There is no way to go back a page.",
"severity": {
"type": "list_node",
"id": "1002"
},
"phase": {
"type": "phase",
"id": "1001"
},
"name": "When advancing to last page in catalog, an error occurs."
},
{
"parent": {
"type": "work_item_root",
"id": "1001"
},
"release": {
"type": "release",
"id": "1002"
},
"description": "Takes too long to load shopping cart. It can take more than 45 seconds.",
"severity": {
"type": "list_node",
"id": "1002"
},
"phase": {
"type": "phase",
"id": "1001"
},
"name": "Takes too long to load shopping cart."
}]
}
*** Response ***
{
"total_count": 2,
"data": [{
"type": "defect",
"id": "1071",
},
{
"type": "defect",
"id": "1070",
}],
"exceeds_total_count": false
}
Example: POST – Partial Success, on defects
This example demonstrates partial success when trying to create a defect while referencing a non-existing release ID 4321.
-
Request: Data array of entity objects to create.
-
Response: Data array of entity objects created successfully.
-
Each object contains an ID.
-
Also, an error array of error objects for entities for which the creation was not successful.
If a request was partially fulfilled, and more than one entity ended in error, an index (entity_index) is returned. entity_index indicates the index of the entity in the request "data" array to which the error refers. The index starts from 0, not 1.
-
*** Request ***
POST.../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects
{
"data": [{
"parent": {
"type": "work_item_root",
"id": "1001"
},
"release": {
"type": "release",
"id": "1002"
},
"description": "When advancing to last page in catalog, an error occurs. There is no way to go back a page.",
"severity": {
"type": "list_node",
"id": "1002"
},
"phase": {
"type": "phase",
"id": "1001"
},
"name": "When advancing to last page in catalog, an error occurs."
},
{
"parent": {
"type": "work_item_root",
"id": "1001"
},
"release": {
"type": "release",
"id": "4321"
},
"description": "Takes too long to load shopping cart. It can take more than 45 seconds.",
"severity": {
"type": "list_node",
"id": "1002"
},
"phase": {
"type": "phase",
"id": "1001"
},
"name": "Takes too long to load shopping cart."
}]
}
*** Response ***
HTTP/1.1 409 Conflict
{
"total_count": 1,
"data": [{
"type": "defect",
"id": "1072"
}],
"exceeds_total_count": false,
"errors": [{
"index": 1,
"error_code": "platform.entity_not_found",
"correlation_id": "31k7vq1wp3kk8idyy1lo39gw6",
"description": "The entity by id 4321 of type release does not exist",
"description_translated": "The entity by id 4321 of type release does not exist",
"properties": {
"entity_type": "release",
"entity_id": "4321"
},
"stack_trace": "platform.exception.EntityNotFoundException: The entity by id 4321 of type release does not exist..."
}]
}
Example: POST request for workspaces
This example demonstrates how space admins can create a workspace in the space context.
-
Request: Data array of workspace objects to create.
-
Response: Data array of workspace objects created successfully, each object contains an ID.
POST .../api/shared_spaces/1001/workspaces
{"data":[
{
"name":"myWorkspace"
}
]
}
See also:
