Entity

POST /api/entities

Adds a new entity. The link to the associated Entity Definition Resource is required. The self property is ignored and may be omitted. If the request body contains an id, the request is treated as a possible UPSERT. If the id is omitted and only an identifier is provided, the request returns a conflict instead of updating the existing entity. The request then checks for the existence of the entity and if the response is positive, then it updates the entity based on the provided body elements.

Success is indicated by returning a 201 Created response, where a Location header contains the URL of the newly created resource. When UPSERT functionality was triggered the response will be dependent on the provided details. When an id is present the header will contain the same Location property as with a normal POST response. When an identifier is used the header will contain an X-Global-Identifier property with the updated identifier as its value.

Tip

It is not possible to set relations while creating an entity unless the relations are nested. Additionally, this functionality is available only through the REST API and not through the Web Client SDK. For non-nested relations one call shall be made for each relation that shall be updated.

Example Request:

RequestResponse

POST http://<hostname>/api/entities
Host: hostname
Content-Type: application/json

{
    "properties":{
        "Property1":"Some value",
        "Property2":42
    },
    "relations": {
        "FinalLifeCycleStatusToAsset": {
            "parent": {
                "href": "http://<hostname>/api/entities/{id}"
            }
        }
    },
    "entitydefinition":{
        "href":"http://<hostname>/api/entitydefinitions/EntityDefinition1"
    }
}

Example response:

RequestResponse

HTTP/1.1 201 Created
Location: http://<hostname>/api/entities/2

GET /api/entities/id

Returns an Entity Object that contains the state of the entity.

Example request:

RequestResponse

GET http://<hostname>/api/entities/1
Host: hostname
Accept: application/json

Example response:

RequestResponse

HTTP/1.1 200 OK
Content-Length: content length
Content-Type: application/json; charset=utf-8
ETag: "hash string"

{
    "id":100,
    "identifier": "00amyWGct0y_ze4lIsj2Mw",
    "properties":{
        "Property1":"Some value",
        "Property2":42
    },
    "relations":{
        "Parent":{
            "href":"http://<hostname>/api/entities/1/relations/Parent"
        }
    },
    "self":{
        "href":"http://<hostname>/api/entities/1"
    },
    "entitydefinition":{
        "href":"http://<hostname>/api/entitydefinitions/EntityDefinition1"
    }
}

GET /api/entities/identifier/uniqueid

Gets an entity by its unique identifier. The response is identical to the one from GET /api/entities/id.

Example request:

RequestResponse

GET http://<hostname>/api/entities/identifier/00amyWGct0y_ze4lIsj2Mw
Host: hostname
Accept: application/json

PUT /api/entities/identifier/uniqueid

Updates an entity with the state submitted in the request. If successful, the server responds with 204 No Content. The request body must contain an Entity Object and its entity definition. The id, relations and self properties are ignored, and may be omitted.

Example request:

RequestResponse

PUT http://<hostname>/api/entities/identifier/00amyWGct0y_ze4lIsj2Mw
Host: hostname
Content-Type: application/json
{
    "properties":{
        "Property2":43
    },
    "entitydefinition":{
        "href":"http://<hostname>/api/entitydefinitions/EntityDefinition1"
    }
}

Example response:

RequestResponse

HTTP/1.1 204 No Content

DELETE /api/entities/identifier/uniqueid

Deletes the entity. If successful, the server responds with 204 No Content.

Example request:

RequestResponse

DELETE http://<hostname>/api/entities/identifier/00amyWGct0y_ze4lIsj2Mw

Example response:

RequestResponse

HTTP/1.1 204 No Content

PUT /api/entities/id

Updates an entity with the state submitted in the request. If successful, the server responds with 204 No Content. The request body must contain an Entity Object, and all properties are expected. The id, entitydefinition, relations and self properties are ignored, and may be omitted.

Example request:

RequestResponse

PUT http://<hostname>/api/entities/2
Host: hostname
Content-Type: application/json
{
    "properties":{
        "Property2":43
    },
    "entitydefinition":{
        "href":"http://<hostname>/api/entitydefinitions/EntityDefinition1"
    }
}

Example response:

RequestResponse

HTTP/1.1 204 No Content

DELETE /api/entities/id

Deletes the entity. If successful, the server responds with 204 No Content.

Example request:

RequestResponse

DELETE http://<hostname>/api/entities/2

Example response:

RequestResponse

HTTP/1.1 204 No Content

POST /api/entities/{entityId}/copy

Copies the entity with id=entityId into a target entity. The target entity can be a new entity or an existing one.

The general body structure of the request is:

RequestResponse

{
  // Identifier of a copy profile that could be used for copying of an entity
  "copy_profile_identifier": string 

  // Id of an entity that will be updated by copying values from an original entity
  "copy_profile_id": long? 

  // Id of an entity that will be updated by copying values from an original entity
  "destination_entity_id": long? 

  // Relations copy options 
  "relation_copy_options": 
  [
    {
      // Relation name
      "relation": string 

      // Copy method
      "method": string 

      // Copy settings of related entities (the entire general structure)
      "related_copy_options": {} 
    }
  ]

  // Properties copy options: an array of properties configurations
  "property_copy_options": 
  [
    {
      // Property name
      "property": string 

      // Copy method
      "method": string

      // New property value
      "new_value": string 
    }
  ]
}

Important

All parameters are optional.
If you provide both the id and identifier of a copy profile, only the latter is considered.
If you provide either property or relation copy properties, the id and identifier of the copy profile are not taken into account.

The available relation copy methods are:

Keep: creates references to the same associated entities (keeps the same ids).
Remove: creates an empty relation (removes all ids).
Copy: creates references to copies of the associated entities (copies related entities and links them).
Overwrite: replaces all references with new ones (sets new ids).
Append: adds a new reference while keeping the existing ones (adds a new id to the existing ones).
Ignore: skips the relation and keeps the original values of the destination entity (in the case where the target entity is a new entity, the value is null).

The available property copy methods are:

Keep: applies the value of the source entity to the target entity (default method)
Remove: set the target property value to null.
Overwrite: overwrites the target property value with a new value.
Ignore: ignores the source entity value and keeps the value of the target entity.

The following examples illustrate different copy requests. The structures of the requests are identical, only their JSON payload changes.

RequestResponse

POST http://<hostname>/api/entities/{entityId}/copy
Host: hostname
Content-Type: application/json

Example 1

RequestResponse

{
  "property_copy_options": [
    {
      "property": "BlockName",
      "method": "Overwrite",
      "new_value": "Block A"
    }
  ],
  "relation_copy_options": [
    {
      "relation": "BlockToTask",
      "method": "Copy",
      "related_copy_options": {
        "property_copy_options": [
          {
            "property": "DoneDate",
            "method": "Remove"
          }
        ],
        "relation_copy_options": [
          {
            "relation": "TaskToAssetDeliverables",
            "method": "Remove"
          }
        ]
      }
    }
  ]
}

Example 2

RequestResponse

{
  "copy_profile_id": 777,
  "destination_entity_id": 12345
}

Example 3

RequestResponse

{
  "copy_profile_identifier": "M.EntityCopyProfile.SomeProfile"
}