Sign in

v1

latestOpenAPI 3.0.22026-07-174950145.6 KB
Write Features

Modify features in the space

This method allows to create, update and delete features. The behavior of the POST handler is controlled by three query parameters described in detail below. The name of the parameter reflects a condition to be matched. Its value reflects the corresponding action to be performed for this case.

If no values are provided, the request is handled with the default values:


ne=create&e=patch&transactional=true

The three parameters and their possible values are:

ne - If Not Exists

If no feature with the provided ID exists, or if the provided feature contains no ID, then one of the following actions can be used:

  • create (default) - A new object is created.

  • retain - No action is executed, allowing the execution of the batch operation to continue, even if the transactional parameter is set to true.

  • error - If no object with the provided ID exists, an error is raised, which would result in the whole batch operation to be aborted, if the transactional parameter is set to true.

e - If Exists

If an object with the provided ID exists, and history is enabled for the space, there are 2 states which could be taken into account:

1. The __ORIGIN__ state - the state that the client received and modified. The state is retrieved by using the value of the NS attribute _version_.

2. The __HEAD__ state - the current state of the object in the space, including any changes applied to it in the meantime.

The possible operations in detail:

  • patch (default) - The feature object is handled as a partial update object. Therefore it could contain only the properties, which should be modified. Properties, which do not exist in the HEAD state of the object are inserted, the values for all existing properties are updated, unless the value of the property is set to null , which will result in the property being removed from the object.

    If an ORIGIN state is specified in the partial update object and it is not the same as the HEAD state, the patch is applied to the HEAD state, but only in case that the differnce between ORIGIN and HEAD contains no conflicting changes( i.e. only different properties were modified ). Otherwise an error is raised, which will result in the batch operation being aborted, if the transactional parameter is set to true.

  • replace - If an object with the provided ID exists, it will be replaced with the provided feature object. If the ORIGIN state is specified in the provided feature and differs from the HEAD state, then a error is raised.

  • merge - The provided feature object is handled as a full object version and not a partial update. If an ORIGIN state is specified in the feature and it is not the same as the HEAD state, the difference between the ORIGIN state and provided version to the HEAD state, but only in the case that the difference between ORIGIN and HEAD contains no conflicting changes. Otherwise an error is raised, which will result in the batch operation being aborted, if the transactional parameter is set to true.

  • delete - The feature with the provided is deleted.

  • retain - The current state of the feature is retained and included in the response.

  • error - Raises an error, if the object already exists.

transactional - Transactional batch operation

Defines, if modifying of the features, is executed as a single transactional batch operation (true:default) or as independent operations (false). There is a limit of 10 megs of data allowed for this operation.

post/spaces/{spaceId}/features

Path parameters

spaceIdstring required

The unique identifier of the space.

Query parameters

e'patch' | 'replace' | 'merge' | 'delete' | 'retain' | 'error'

The action to execute, when a feature with the provided ID exists. Default is patch.

ne'retain' | 'error' | 'create'

The action to execute, when a feature with the provided ID does not exist or the feature contains no ID. Default is create.

cr'error' | 'retain' | 'replace'

The resolution strategy when a conflicting update of the same attribute occurs. To keep the value of the head state select retain. To overwrite the value of the head state select replace. To abort the entry update select error.

transactionalboolean

Defines, if this is a transactional operation. Default is true.

prefixIdstring

If set all feature IDs are prefixed with the provided string.

context'default' | 'extension' | 'super'

The context where the operation will be performed on a composite space. If not specified, the operation occurs based on the extension rules. For additional information, see Space.extends.

Available context are:

ContextDescription
defaultThe default value if none is given. For composite spaces the operation occurs based on the extension rules. For normal spaces this is the only valid context.
extensionThe operation will be executed only in the extension and no operation will be performed in the extended space.
superOnly applicable for read-operations. The operation will be executed only in the space being extended (super space).
versionRefstring

The query parameter used to specify the target version reference when reading or writing features. A reference describes a target tag or a branch and/or a version within that target branch.

Default is: main:HEAD

<br> Version references have the following syntax: <br> `[<branchName (optional, default: main)>:][<version (optional, default: HEAD)>] | [<tagName> (optional)]` <br> The "main"-branch is pointing to the space itself as it has been created in the first place. Defining the branch as part of the reference only becomes necessary if further branches have been created for the space, which should be addressed by the ref. <br> Depending on the use-case it can be necessary to specify a range of versions rather than only one version. In such a case the version part of the Ref would look like: `<start>..<end>`

Where <start> is the start of the range (exclusive) and <end> is the end of the range (inclusive).

Another way of specifying a version range is using the star-symbol: *

Using * refers to "all available versions" in the space or branch and is only applicable in the cases in which a version range may be provided.

<br> Samples: - `main:42` points to version 42 of the "main"-branch - `myTag` points to the version of the tag with ID "myTag" - `myBranch:37` Points to version 37 of the branch with ID "myBranch" - `42` points to version 42 of the "main"-branch - `myBranch:HEAD` points to the latest version of the branch with ID "myBranch" - `HEAD` points to the latest version of the "main"-branch - `myBranch` points to the latest version of the branch with ID "myBranch" - `myBranch:0..HEAD` points to all available versions of the branch with ID "myBranch" - `0..HEAD` also points to all available versions of the "main"-branch - `*` also points to all versions (short form) - `myBranch:*` also points to all versions of branch "myBranch" (short form) - `main:5..10` points to the versions in the interval `]5, 10]` of the "main"-branch - `5..10` also points to the versions in the interval `]5, 10]` of the "main"-branch

Response

An array of features and their modifications response.