Share this page

# POST: Create instances in a collection

This topic provides instructions for using the POST operation to create entities.

In this topic:

## 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:

1. 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.

2. 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.

3. POST the data to the collection.

4. 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.

Back to top

## 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
    }

Back to top

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..."
                    }]
    }

Back to top

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"
      }
     ]
    }

Back to top

See also:

- Resources
- Collections
- Instances (Entities)

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 23.4-24.3 All View Local Help Center View Online Help Center Version: