Commands

Each rendering request is a sequence of commands that instruct the rendering server to perform its operations. Depending on the command, it applies to a current layer or globally.

The rendering server accepts GET and POST requests:

GET is used for most rendering operations, making it possible to use images generated by the service in a variety of contexts, for example in background-image CSS property, and a source for an <img> tag, or as a direct download.
POST requests are typically used to upload a user-generated image or perform a special operation.

The general request URL form shall be in the format:

https://fx.images.drivecommerce.com/api/v1/<client name>/image/?<rendering commands>

Where client name is the client’s account name provided by the Drive Commerce support team
and rendering commands is a list of parameters that describe the visualization operations.

Versioned URLs

Additionally, the rendering request can include a built-in version ID. Version IDs are not tied directly to an asset instance or upload date, instead, they serve as a client-defined ID that requests the server to generate a fresh new download, ignoring the previously cached data.

The version URL format is:

https://fx.images.drivecommerce.com/api/v1/<client name>/image/ref/<cache version ID>?<rendering commands>

Where cache version ID is 6 arbitrary alpha-numeric characters.

For example:

https://fx.images.drivecommerce.com/api/v1/drive/image/dog - unversioned URL
https://fx.images.drivecommerce.com/api/v1/drive/image/ref/ABCDEF/dog - versioned URL

Command List

The commands list shall follow the general GET request query string conversion:

A list of commands shall be in the format parameter-name=parameter-value.
If multiple commands are provided, they shall be separated by semi-colons: var1=value1&var2=value2&...
Parameter values shall be percent encoded, according to HTTP standards. See encodeURIComponent function documentation for more details.

Compound command parameters

Some commands take complex parameters that allow to quickly configure multiple aspects of a single command, for example, when a command requires multiple values to be configured to work properly. In that case, the parameter value for the command should be a list of additional parameter names and values pairs. Each name and respective value shall be separated by : (colon) string, and value pairs shall be separated by ; (semi-colon) characters.

For example: fnt=f:Times;s:250 defines a fnt (font) command that renders text using Times font at 250 pixels font size.

Compound commands

Additionally, some commands allow to define multiple “sub-commands”. For example, effects rendering request command fx takes in a list of effects to apply.

Compound commands shall be a comma-separated list of sub-commands. Each sub-command may have a list of parameters provided inside (...) characters following the command name.

For example: fx=thrd(w:5;...),shadow(x:1;y:1;...) command applies thread rendering simulation (thrd) and drop shadow effects (shadow)

In many cases, sub-commands can be specified using one or multiple instances of the main command and are combined together during the layer rendering. For example, the above command:

fx=thrd(w:5;...),shadow(x:1;y:1;...)

can also be defined as:

fx=thrd(w:5;...)&fx=shadow(x:1;y:1;...)