Retrieve objects as deep links

GET /api/v1/objects/...

Returns a user object or asset in the specified format

If an authorized session is provided, the search will be performed using it. Else, the search will be conducted on behalf of the system user “deep_link”.

Path parameters

The path parameters specify which object or asset is being accessed. It is organized in “path parts”, consisting of one or more path entries.

The path parts can be given in any particular order.

Path part: object selection

Objects can be accessed in one of three ways. One and only one of the following has to be provided:

Object Selection by System Object ID

GET /api/v1/objects/id/1

Object Selection by System Object UUID

GET /api/v1/objects/uuid/12345678-abcd-1234-5678-abcdef123456

Object Selection by searching for an unique column value

GET /api/v1/objects/column/example_object/reference/ref123

Path part: mask selection

If not specified, the object will be returned in the best mask.

GET /api/v1/objects/id/1/mask/mask-name

GET /api/v1/objects/uuid/12345678-abcd-1234-5678-abcdef123456/mask/mask-name

GET /api/v1/objects/column/example_object/reference/ref123/mask/mask-name

Path part: version selection

These parameters allow to ask for a specific version of the object. The object will be rendered in the schema version that was current when the object version was created. A mask specification is not possible and will be ignored.

The object is rendered in the _all_fields mask of the old version. This means the object will be rendered with all fields of the old schema version. This means especially, that old field names and types will be used. Schema changes since this object version was created will not be visible.

The version can only be requested in combination with /api/v1/objects/id and /api/v1/objects/uuid, it is not allowed for /api/v1/objects/column.

It is not possible to combine them:

Latest (current) version

This is the default behaviour.

GET /api/v1/objects/id/1/latest

GET /api/v1/objects/uuid/12345678-abcd-1234-5678-abcdef123456/latest

GET /api/v1/objects/column/example_object/reference/ref123/latest

will return the same object version as

GET /api/v1/objects/id/1

GET /api/v1/objects/uuid/12345678-abcd-1234-5678-abcdef123456

GET /api/v1/objects/column/example_object/reference/ref123

A specific version by version number:

GET /api/v1/objects/id/1/version/1

GET /api/v1/objects/uuid/12345678-abcd-1234-5678-abcdef123456/version/1

Note: The version selection can not be combined with /api/v1/objects/column/!

A specific version by date:

GET /api/v1/objects/id/1/date/2018-12-10

GET /api/v1/objects/uuid/12345678-abcd-1234-5678-abcdef123456/date/2018-12-10

Note: The selection by date can not be combined with /api/v1/objects/column/!

Path part: file selection

If specified, an asset will be returned.

There are several options:

For file/column/<name>/<n>, the position is used to get an asset from a field inside a nested table. n is the position of the field inside the nested table.

For assets in a single field, the position is ignored and the single asset will be returned. This is different from the fylr API, where the position is not allowed if the field is not inside a nested table.

The position values start at 1.

Note: if the path has more parts, the position value must be given to avoid problems with the path parser.

• This means for example, if the asset column <name> is not inside a nested table, that

    <server>/api/v1/objects/id/1/file/column/<name>
  

  is valid and will return the same file as

    <server>/api/v1/objects/id/1/file/column/<name>/1
  

• If more path parts are specified, the position must always be given:

    <server>/api/v1/objects/id/1/file/column/<name>/file_browser/preferred
  

  is invalid and will cause an error, instead

    <server>/api/v1/objects/id/1/file/column/<name>/1/file_browser/preferred
  

  must be used.

Path part: file version selection

Only valid in combination with file. Defaults to “preferred”.

Note: This setting is ignored if the file is accessed directly through id.

There are two options:

Path part: asset version selection

Only valid in combination with file. Defaults to version “original”.

Note: This setting is ignored if the file is accessed directly through id.

There are two options:

Path part: format

This setting is only used for objects. The format of files is defined by the files themselves.

The default format is JSON.

GET /api/v1/objects/id/1/format/json

GET /api/v1/objects/id/1/format/xml_easydb

GET /api/v1/objects/id/1/format/csv

GET /api/v1/objects/id/1/format/xslt/<xslt-name>

Content-Type in Header for XSLT format

If a XSLT format is selected, the HTTP Header Content-Type is set depending on the content of the XSLT file. The attributes "media-type" and "method" of the <xsl:ouput> tag (see https://www.w3schools.com/xml/ref_xsl_el_output.asp) are analyzed to determine the best Content-Type for the response:

• if "media-type" is set:

  • use attribute value as is

• if "media-type" is not set:

  • check "method" to determine a fallback:

    • "xml": "text/xml"
    • "html": "text/html"
    • "text": "text/plain"
    • "name": "text/plain"
    • "json": "application/json; charset=utf-8"

  • if method was none of the above:

    • use "text/plain"

Path part: disposition

Sets the content disposition header. Defaults to:

• unset for objects
• “attachment” for files

Query String

The query string specifies formatting, as well as the session used to access the object.

Output

If file is provided, the output is a redirect to the requested file.

Else, the output is an object in the requested format.

Permissions

The user (provided through token or auth) needs the “read” right for the requested object and the “mask” right for the given mask (see rights management).

If the token is not provided, the following base config parameters are checked:

• system.deep_link_access.enabled is required for any operation
• system.deep_link_access.allow_access_by_ids is required when using the id object selection parameter
• system.deep_link_access.allow_access_by_unique_columns is required when using the column object selection parameter

HTTP status codes