REST interface

With the REST interface system type, DDM fetches documents from a system that offers them through an HTTP interface – a DMS, a PIM, a shop, your own application. Unlike with SharePoint or FTP, DDM does not know how this interface is built. You describe it in a request chain: which addresses DDM calls, where in the response the list of documents is and what each value means.

That sounds more technical than the other sources – and it is. Expect to need somebody who knows the interface and has its documentation to hand.

What the interface must be able to do

DDM needs two things from it:

1. A list of the documents as JSON (or XML) – with at least a name and an address where the file is.
2. The file itself at this address, retrievable with a simple GET.

Authentication is with one fixed header, e.g. an API token. A sign-in that first fetches a token can be modelled as a step of its own – see Example 3.

1. Add the source

Under Settings › External sources, add a source with New source, give it a name and choose REST interface as the System type.

DDM sends this header only to the base URL – more precisely: to addresses with the same protocol, host and port. If a step calls another address or a file is on another server, the header is not sent there.

Click Test connection. DDM calls the base URL with GET and the header.

2. Understanding the request chain

Under Request chain & field mapping, add one or more steps with + Step. Each step is one call to the interface. The steps run one after another:

• A step can iterate over a list in its response – for each entry, the next step runs once.
• A step can hand values on to the following ones as variables, e.g. a folder's ID.
• A field mapping says which value of the response is which detail of a document: name, file URL, category …

At the end, every entry of the last step that returned entries becomes a document – provided it has a name and a file URL.

A step

With the arrows Move up / Move down you change the order.

Path and base URL

A step's path always goes below the base URL – whether it starts with / or not:

A document's File URL is different: it comes from your interface's response and is read like a link. If the interface returns /files/4711, DDM downloads https://dms.company.com/files/4711 – from the server root, not below /api/v1. That is what interfaces mean by such addresses.

Paths in the response

You give the place where a value is as a dotted path – not JSONPath, not XPath:

{
  "data": {
    "items": [
      { "id": 4711, "title": "Pricelist 2026", "file": { "url": "/files/4711" }, "tags": ["sales"] }
    ]
  }
}

Paths in variables and field mappings always apply to one entry of the iterated list, not to the whole response.

Variables

Under Variables for later steps, set a Variable name and a JSON path with + Variable. In every later step you insert the value with {{name}} – in the Path, the Headers or the Body:

• Path: folders/{{folderId}}/files
• Header: Authorization: Bearer {{token}}
• Body: { "folder": "{{folderId}}" }

DDM inserts the values appropriately: URL-encoded in the path, in the body as JSON or XML text depending on the content. A variable name may only contain unaccented letters, digits, _, . and -. Under Incoming variables, each step shows which variables the earlier ones provide; one it uses is highlighted.

A path that consists only of a variable containing a full address – {{nextPage}} – is called unchanged.

Field mapping

Under Field mapping (JSON → attribute), map a path to a detail of the document with + Mapping:

Mappings in earlier steps apply to all entries that arise below them. So step 1 can, for example, provide the Category path from the folder name, and step 2 the name and file URL of the files in it.

Transformations

Every variable and every mapping can reshape the value before it is used:

Beside each row, a preview shows what becomes of the first entry of the example response.

3. Test the chain

Click Test chain (or Test on a single step). DDM calls the steps without importing anything, and shows

• a status per step: ok, failed, skipped, unreachable, rejected, redirected or address blocked,
• under Example response, the step's response (the first 20,000 characters) – the basis for the previews,
• how many records resulted,
• in the Import scope under Structure preview, which path would go into which category,
• under Group mapping, the Groups found.

If a step fails (HTTP status 400 or above, or no response), the chain stops and the following steps are set to skipped. Beneath the failed step you see what came back – the status and the start of the response, e.g. the interface's error message. The Example response keeps the last successful response, so the previews are not lost. You can also paste the Example response by hand – e.g. from the interface's documentation – to prepare mappings before the connection is in place.

Once the chain works, sync once with Sync now in the Import scope and switch on Source active – see Overview.

Examples

Example 1: One list, one call

The interface returns under GET /documents:

{ "items": [ { "id": "4711", "title": "Pricelist.pdf", "url": "/files/4711", "folder": "Sales/Prices" } ] }

Step 1 – „Documents": GET documents, Iterate over list items.

Example 2: First the folders, then their files

GET /folders returns the folders, GET /folders/{id}/files the files of a folder.

Step 1 – „Folders": GET folders, Iterate over list items.

• Variable id = id
• Mapping name → Category path

Step 2 – „Files": GET folders/{{id}}/files, Iterate over list files.

• Mappings title → Document name, url → File URL, fileId → External id

Step 2 runs once per folder from step 1; each file gets the category path of its folder.

Example 3: Sign in first, then fetch

After POST /auth/token, the interface returns a short-lived token:

{ "access_token": "eyJhbGc…", "expires_in": 3600 }

Step 1 – „Sign in": POST auth/token, Body:

{ "client_id": "ddm", "client_secret": "…" }

• Variable token = access_token
• Iterate over list: empty

Step 2 – „Documents": GET documents, Headers Authorization: Bearer {{token}}, Iterate over list items, mappings as in example 1.

The downloaded files only get the header from Authentication (header) – not the token from step 1. If your server requires the token for the files too, the file URL itself must contain the access (such as a signed address), or the server must deliver files with the fixed header.

Group mapping

If your interface returns a group for each document – a department, a role, a customer group –, DDM can turn it into read access:

1. In the chain, map the group's path to the External group attribute.
2. Click Test chain. Under Group mapping, the Groups found appear.
3. Click a group found (or + Mapping and type its name) and choose the DDM group that gets it.

On sync, every document gets read access for the DDM group mapped to its external group – in addition to the permissions of its category. Upper and lower case do not matter.

• Without a mapping, with No group or with Mapping active switched off, the import grants no rights for this group.
• Each document can have one external group.
• The import only grants rights, it never withdraws them. If a document's group changes in your system, the old DDM group keeps its read access – withdraw it on the document if needed.

Limits

DDM does not follow redirects (HTTP 3xx) – enter the target address directly.

There is no built-in paging (pagination): each step runs once per entry of the previous one, not „until nothing more comes". If your interface returns pages, request pages as large as possible (e.g. ?limit=200), or model a fixed number of pages as steps of their own – for instance with the variable {{nextPage}} from the first page's response as the path of the second step. If the maximum number of calls is reached, the test reports Stopped at the maximum number of calls …; split the source up then.