Skip to main content

Dictionary module export

API resources

This article refers to the following API resources:

  • Method: GET
  • Endpoint: /{dataType} (e.g.: /sources, /containers, /structures, /fields)
  • Description: Paginated endpoint that fetches a list of Dictionary objects
  • Authentication: Bearer token
Requirements

Before you start reading this guide, make sure you are familiar with the following API concepts:

You also need basic knowledge on the Dictionary module. Take a minute to learn about it with our functional documentation 🔗

Overview​​

The Dictionary module has two main particularities making it different from the other modules :

  1. it has four types of objects, also referred as dataTypes in the API : sources, containers, structures, fields
  2. some object types can be recursive, such as the containers and structures types. Meaning they can have children objects of the same type, e.g. a container object can have another container object as child.

In order to fetch every object contained in your Dictionary module, we will elaborate a four steps workflow and go over the specifics of each API request, paginated endpoints and the potential recursive parent-child patterns you might encounter.

Workflow overview​​

The goal here is to fetch objects and their children, starting from the source objects, and going through each object type until we don't have any more to fetch.

This can be operated in four steps :

  • Fetch the root objects, i.e. sources objects
  • For each source object, we need to fetch its children, the structures and containers objects
  • For each container object, we will fetch its children of type containers and structures, and repeat this step every time we find a container child object
  • For each structure, we fetch its field children and its structure children recursively until there is no more

The following diagram should make it less daunting:

dictionary-export.svg

Workflow in depth​

1. Fetching source objects​

This step is the easiest and most straightforward. It uses the GET /sources endpoint.

Let’s get over the request parameters :

  • versionId, set it to target the workspace you want to fetch your sources from (refers to versionId basics)
  • limit, set it to 5000 to maximize the number of objects fetched per request, thus lowering the amount sent to the server
  • page, its starting value should be 1, but as we will cover next, it might be incremented
  • includeAttributes, set it to true to receive the objects with their attributes

You should end up with this request URL :

/sources?versionId={yourVersionId}&includeAttributes=true&limit=5000&page=1

Send this request and store the objects contained in the API’s response.

If the response payload’s next_page property contains a URL to the next page, you should repeat step 1 with this URL until next_page's value is null.
This looping process will make sure you fetch every source object.

Once you have fetched and stored every sources, you can move on to step 2.

2. Fetching the direct children​

This step will be executed once for every object we previously stored. The endpoints used will be GET /containers and GET /structures.

The request parameters will be the same as step 1 with two new ones :

parentId, set it to the source object entityId value to limit your request scope to this object’s children only

maxDepth, set it to 0 to fetch only the direct children

Your request URL should look like this :

/containers?versionId={yourVersionId}&includeAttributes=true&limit=5000&page=1&parentId={parentId}&maxDepth=0

and

/structures?versionId={yourVersionId}&includeAttributes=true&limit=5000&page=1&parentId={parentId}&maxDepth=0

Send the requests with /containers and /structures to fetch both container and structure objects, and store them.

Just like step 1, repeat the process for as long as next_page contains a URL to the next page.

3. Handling container objects recursion​

As mentioned in the Overview section, containers are recursive objects that can contain other containers and structures.

So for each container object fetched in step 2, execute step 2 with the container’s entityId as parentId.

4. Handling structure object's children​

Similar to container objects, structure objects can be recursive, but they can also contain field objects.

Just like step 3, for each structure object fetched in step 2 and / or 3, execute step 2 with the structure’s entityId as parentId but call the /structures and /fields endpoints instead of /containers and /structures.

Code example​​

We made a minimalistic code example written in Javascript for you to try and play with.​

Upon executing the script, it will fetch every object contained in your Dictionary module and store them in a JSON array, each entry will be a tree of objects similar to the one required to create a tree of dictionary objects using the POST /sources/bulktree/{versionId} endpoint.
The end result will then be saved to a file.

You can find it here on StackBlitz.
StackBlitz let's you run the code directly from the web, no download or install required, you have to :

  1. ✍️ edit the project configuration with your API url, your versionId and your accessToken

  2. 🚀 run npm start

  3. 🎁 collect your Dictionary export