Overview

There are several service lines that work on the same principle. The end points are slightly different but the parameters are the same and depending on the configuration, the possibilities are the same. All details are available in section https://crossmedia.atlassian.net/wiki/spaces/WD/pages/732364803. This page describes the general principle of creating and modifying resources, uploading binary files, etc.

Create

The end point for creating a resource is as follows:

• verb: POST

• general form of the URI: /api/rest/{type of service}/{name of the resource type}

See the description of response.

Create a resource from metadata

To create a resource, simply post a json that describes its properties. Unknown or unmanaged properties will be ignored. It is also possible to pass a property through a multipart-formdata field or in the query part of the request. See details in the Passing metadata chapter bellow.

Create a resource from binary file (upload)

You can upload a binary file using a multipart-formdata field. The file name (Content-Disposition) in the field will be used to name the file. It is possible to modify the name by passing the name of the file in a field with the same name, or by passing a parameter in the query part of the URL. See details in the chapter below.

It is also possible to transmit the file via the body of the request. In this case, it is essential to provide the name of the suffixed file (with its extension), because it is by the suffix that the type of file will be determined. The content-type must be application/octet-stream.

A base 64 value will also be treated as a binary file.

When using a field or a parameter to upload a file, its name must of course correspond to the name of a property of the resource which is of type file or image. It is possible to use another name. In this case, a parameter corresponding to the property of the resource must be passed with a specific uri value of the form cid:<name>, where <name> is the name of the file field.

Create a resource from binary file with data

You can pass both the binary and the JSON describing the properties of the resource by passing them each in a multipart-formdata field.

For example,

Create a resource from URL or file path

It is possible to pass in a property of type file or image a URL of protocol http or file.
If the URL is of type http, the stored image will be downloaded from the URL. Images can only be downloaded from authorized URLs (see WXM_RESTAPI plugin configuration). If the URL is of type file, the path is considered as relative to the SAN, and must be authorized (see WXM_RESTAPI plugin configuration)

Archive files

It is possible to upload an archive file so that a resource is created for each media (entry) it contains. By default, only one resource is created for a POST. You have to specify the parameter unzip=true to trigger the creation for each content of the archive. If you provide metadata, it will be applied to all created resources. By default, the resource name is the name of the entry in the archive. Some entries will be ignored, especially hidden files, empty entries, etc.

Asynchronous mode

By default, the invocation of the creation service will wait until it has finished creating all the resources before responding. It is possible to invoke the service so that it responds immediately. In this case, a process identifier is returned to you and you can use it to find out the progress of the process, by interrogating the end point at regular intervals.

To activate this mode, set the parameter asyncUnzip=true. If this parameter is set to true, unzip=true parameter can be omitted.

Supported archive formats

• zip, zip4

  • extension zip

• UNIX tar archive

  • extension .tar

• compressed (gzip, rfc1952) tar archive

  • extensions .tar.gz, .tgz

• Java archive

  • extension jar

• bzip

  • extensions .tar.bz, .tbz

• bzip2

  • extension .tar.bz2

• ARJ (single volume)

  • extension .arj

• Seven zip

  • extension .7z

• .ar

• .cpio

Modify

The end point for modifying a resource is as follows:

• verbs: PUT

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/{id of the resource}

It’s possible also to use a POST alias:

• verb: POST

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/{id of the resource}/put

Modifying a resource

To modify a resource, use PUT verb. The parameter passing is done exactly the same way as for the creation (POST).

Partial changes

The end point to partially modify a resource is as follows:

• verb: PATCH

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/{id of the resource}

It’s possible also to use a POST alias:

• verb: POST

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/{id of the resource}/patch

Modifying a resource

Depending on the configuration of the resource, when making a modification, all properties can be mandatory or only some.. To be able to modify only one or a few of the mandatory properties, use the partial modification. The configuration can also make some properties mandatory for the partial modification.

Modification of several resources

It is possible to apply the same modification to several resources. The end point is the same, in modification, as in partial modification, but either you pass several identifiers separated by a comma, or you pass a selection request by the query parameter.

Examples:

• PUT /api/rest/dam/data/asset/12,42,63 to modify the assets 12, 42 and 63.

• PUT /api/rest/dam/data/asset?query={"coverage":1} to modify assets with coverage equals to 1.

Method overriding

Since multipart-formatdata is not supported by the PUT or PATCH method, if it is necessary to use a PUT or PATCH using multipart-formatdata, use the POST method overriding.

Passing resource metadata

How

The parameters can be passed in the query part of the request, or in a multipart-formdata field. Resource metadata (resource properties) can be passed in a JSON object, as a single parameter. When a property is assigned via JSON, the other parameters corresponding to this property are ignored. When a property is assigned multipart/formdata field, the corresponding query parameter is ignored. It is therefore not possible to modify for example the values assigned via JSON, by modifying the URI (by adding a parameter for example in the query part of the URL).

JSON

The principle is to pass a JSON object in the parameter json. In case of a possible collision with another parameter (for example, if the name of the property containing the asset media is called json), or for any other reason, we can use the parameter jsonParameter to indicate the name of the parameter we want to use.

In this JSON object, the fields are the properties to modify, and their value the corresponding value to assign. Fields that do not correspond to any property, or to any particular parameter are ignored.

This is the preferred mode for passing values to be modified in the resource (or to be assigned to a resource at its creation). It is more powerful and you can type the values (in the other forms of parameters, you can only pass strings, which will be converted into the right type, when it is possible without ambiguity).

Parameters by field

One can pass a value, or several, for a property, using a multipart/formdata field. The name of the field is the name of the property prefixed by prop_ (except for the property designating the media of an asset, which is not prefixed).

Parameters in query

You can also pass the parameters directly in the URI, as you do with a field. This only exists for backward compatibility with legacy services.

What

Standard values

Internationalized labels

Multiple child

String functions

JSON

Modification by value

Response

Facets / Faces

It is possible to get the facets for a property version of a resource. To do this, you can use the creation or modification service in simulation mode. In this case, the object will not be saved in the database.

To activate the simulation mode, pass the parameter simu=true. When this mode is activated, facets are automatically exported (no need to pass the parameter withFacets=true).

Create or update mode

In this mode of operation, you can request a creation that becomes a modification if a resource already exists with the desired characteristics. For example, you can create a value in a list of values, providing a code and a label (without knowing the identifier) and if a resource already exists for this code, you will modify the label of this existing resource, and if it does not exist, you will create it, with this label and this code.

To do this, proceed as for a modification (or partial modification), without indicating the identifier of the resource to be modified. The resource must have been configured to work in this mode.

Headers

The headers are the description of the properties and their characteristics (modifiable, mandatory, type, wording to build a form, etc). See the detail of how it works here.

Locks

It is possible to set an exclusive modification lock on a resource. This should only be used if you are making an editor and the modification should be reserved for the editor's user while it is open. There is no need to lock a resource when using the API as a service (this is already done). The lock has a limited lifetime and should be renewed as needed. It is important to remove the lock as soon as possible to release the resource as soon as possible.

Locking a resource

• verb: POST

• general form of the URI: /api/rest/{type of service}/{name of the resource type}/lock/{id of resource}

Parameters are:

• duration, optional, the lifetime of the lock in seconds. By default, without this parameter, the lifetime is 30 seconds (in general, may depend on the server configuration). Other values mean:

  • 0: The default lifetime (30 seconds)

  • >0: Lifetime in seconds (maximum 600 seconds)

  • -1: The maximum lifetime is that of the session

• await, an optional boolean (default is false). If true, if the resource is already locked by another user, we wait until the lock is removed to set the new lock, otherwise we answer immediately that the resource is already locked by another user.

• awaitTimeout, optional, the timeout for the await parameter, in seconds. By default, without this parameter, the timeout is 30 seconds. Other values mean:

  • 0: The default lifetime (30 seconds)

  • >0: Timeout in seconds (maximum 60 seconds)

  • -1: The maximum timeout (60 seconds)

Extending the life of a lock

All you have to do is call the locking end point.

Unlocking a resource

• verb: DELETE

• general form of the URI: /api/rest/{type of service}/{name of the resource type}/lock/{id of resource}

Read a lock

• verb: GET

• general form of the URI: /api/rest/{type of service}/{name of the resource type}/lock/{id of resource}

You can see if the resource is currently locked and by whom. It is also possible to have this information through the resource access services (by ID or in list), with the parameter showLock (default to false).

Workflows

To change the workflow state of a resource, a state change action must be applied (it is possible for the old workflow system to change the state directly, like any property linked to another resource (here the associated workflow resource), but the resource must be configured to allow it).

See detail at page https://crossmedia.atlassian.net/wiki/spaces/WD/pages/2214330434

Mass import