Skip to main content

Creating multiple objects

API resources

This article refers to the following API resources:

Overview​

This article will cover the creation of a basic SQL Database representation with the following objects:

  • 1 source (My DataBase)
  • 1 container (My Container)
  • 2 structures (table_0 et view_0)
  • 4 fields (column_0 and column_1 for each structure)

The end result will look like this in the DataGalaxy Web App: bulktree-result.png

TL;DR​

  • POST /{dataType}/bulktree/{versionId} endpoints (e.g.: POST /sources/bulktree/{versionId}) can create full trees of objects
  • GET /{dataType}/types endpoints (e.g.: GET /sources/types) help us find available types and their compatible children types
  • object trees are created with a JSON structure where we define our objects, their attributes and their children
  • bulktree endpoints use upsert operations

Sending the request​

Use our Postman Collection to test this POST /sources/bulktree/{versionId} request. (💡 Learn more)

Request payload​

To create multiple objects in the Dictionary module, we will send a POST request to the /sources/bulktree/{versionId} endpoint.

This request will contain a request payload with JSON data representing our objects.

Note

The endpoint contains a placeholder for {versionId}.
This id refers to a version of your workspace and can be found with the GET /workspaces endpoint.

👉 Check out the versionId section from the previous article.

Source object​

First, we need to create a source object representing our SQL Database.

Properties name and type are mandatory to create an object, the others (e.g.: technology, summary, owners, ...) are optional and will be left untouched if you don't set them in your request payload.

The children property is another mandatory property for the source object.
It will contain a list of JSON objects, each refering to a direct child object of your source object.

Request payload
{
  "name": "My DataBase",
  "type": "Relational",
  "summary": "Database summary",
  "technology": "mysql",
  "description": "Database description",
  "owners": ["john.smith@datagalaxy.com"],
  "stewards": ["john.smith@datagalaxy.com"],
  "tags": ["GDPR"],
  "children": [ ... ]
}

Container object​

Moving on to the direct child object of our Database: a container.

Similar to the source object, the children property will contain the container's children objects.

tip

A quick GET request to the /sources/types endpoint will help us find which container types are compatible with the Relational sources type.

Request payload
{
  "name": "My DataBase",
  "type": "Relational",
  ...
  "children": [
    {
      "name": "My Container",
      "type": "Model",
      "children": [ ... ]
    }
  ]
}

Structure and field objects​

Now let's add the container's children: the structures and their fields.

tip

Send a GET request to the /containers/types endpoint to find out what structure types are compatible with the Model type.

Request payload
{
  "name": "My DataBase",
  "type": "Relational",
  ...
  "children": [
    {
      "name": "My Container",
      "type": "Model",
      "children": [
        {
          "name": "table_0",
          "type": "Table",
          "children": [
            {
              "name": "column_0",
              "type": "Column"
            },
            {
              "name": "column_1",
              "type": "Column"
            }
          ]
        },
        {
          "name": "view_0",
          "type": "View",
          "children": [
            {
              "name": "column_0",
              "type": "Column"
            },
            {
              "name": "column_1",
              "type": "Column"
            }
          ]
        }
      ]
    }
  ]
}

Full payload​

Here is what our request payload will finally look like:

Request payload
{
  "name": "My DataBase",
  "type": "Relational",
  "summary": "Database summary",
  "technology": "mysql",
  "description": "Database description",
  "owners": ["john.smith@datagalaxy.com"],
  "stewards": ["john.smith@datagalaxy.com"],
  "tags": ["GDPR"],
  "children": [
    {
      "name": "My Container",
      "type": "Model",
      "summary": "Container summary",
      "children": [
        {
          "name": "table_0",
          "type": "Table",
          "children": [
            {
              "name": "column_0",
              "type": "Column"
            },
            {
              "name": "column_1",
              "type": "Column"
            }
          ]
        },
        {
          "name": "view_0",
          "type": "View",
          "children": [
            {
              "name": "column_0",
              "type": "Column"
            },
            {
              "name": "column_1",
              "type": "Column"
            }
          ]
        }
      ]
    }
  ]
}

Response payload​

Once the API processes the request, it will respond with a status code 201 and a response payload containing a count of the created objects.

Response payload
{
  "total": 7,
  "created": 7,
  "updated": 0,
  "deleted": 0,
  "unchanged": 0
}

Upserting attributes and objects​

Bulktree endpoints use upsert operations, meaning only the difference is applied when you send a request.

For example, sending the same request payload twice will have no effect the second time because no differences were found between the existing objects and those you defined in your payload.

Also, you don't need to define every attribute of every object in your payload each time you send a request. Attributes or objects that are not defined in your request payload will be left unchanged.