Fetching object lists

API resources

This article refers to the following API resources:

• Method: GET
  
• Endpoint: /fields
  
• Description: Paginated endpoint that fetches a list of fields with their attribute and links.
• Authentication: Bearer token

Overview

The GET /{dataType} endpoints (e.g.: GET /fields) are paginated endpoints able to retrieve multiple objects.

These endpoints will fetch objects based on a specific dataType. For example, dataTypes from the Catalog module are sources, containers, structures, fields.

versionId is the only required parameter. It is essential in order to target a specific workspace or version of a workspace.

Basic request

Using Postman

Send this GET /fields request from Postman using our Public Collection. (💡 Learn more)

Using cURL

Here is an example of a cURL request to fetch field objects:

curl -L -X GET 'https://yourapi.datagalaxy.com/v2/fields?versionId=913f3fbb-6d87-49b8-9428-1cea07e25351' -H 'Authorization: Bearer {token}'

Response Payload breakdown

Once the request is sent, the API should respond with a payload similar to the following:

Response payload

{
    "pages": 3,
    "total": 20,
    "total_sum": 51,
    "next_page": "https://yourapi.datagalaxy.com/v2/fields?versionId=913f3fbb-6d87-49b8-9428-1cea07e25351&page=2",
    "results": [
        {
            "id": "0596ec5a-6e36-4476-8875-e76bf1f538b0:380582ac-bb74-4698-91dc-2f24347e3892",
            "name": "ADDRESS",
            "technicalName": "ADDRESS",
            "type": "Column",
            "dataType": "Field",
            "versionId": "913f3fbb-6d87-49b8-9428-1cea07e25351",
            "path": "\\MyDatabase\\CLIENT\\ADDRESS",
            "typePath": "\\Relational\\Table\\Column",
            "objectUrl": "https://yourclient.datagalaxy.com/#/client/4bdbc99e-f9c7-42f7-93e8-a946a5c937e1/space/0596ec5a-6e36-4476-8875-e76bf1f538b0/913f3fbb-6d87-49b8-9428-1cea07e25351/catalog/all/list/tree/browse/380582ac-bb74-4698-91dc-2f24347e3892",
            "location": "fields/913f3fbb-6d87-49b8-9428-1cea07e25351/0596ec5a-6e36-4476-8875-e76bf1f538b0:380582ac-bb74-4698-91dc-2f24347e3892",
            "childrenCount": 0,
            "parent": {
                "id": "0596ec5a-6e36-4476-8875-e76bf1f538b0:dc98bc8b-3635-4d1f-815d-600451ca37be",
                "name": "CLIENT",
                "technicalName": "CLIENT",
                "type": "Table",
                "dataType": "Structure"
            }
        },
        ...
    ]
}

Payload root breakdown

The payload's root is composed of 5 properties:

• pages, total and total_sum provide data to help us manipulate the endpoint pagination
• next_page is a pre-built request url to fetch the next page
• results contain a list of DataGalaxy objects

results breakdown

Every DataGalaxy object contained in the results property contains the following:

• basic information such as the object's id, name, technicalName, type, ...
• objectUrl, a prebuild URL to navigate to the object's details page, in the DataGalaxy Web App
• location, a prebuilt endpoint to fetch the object's details using API
• parent, a property providing basic information on the object's parent

Advanced parameters

parentId - set request scope to the specific parent object

You might need to fetch objects contained in a specific object parent, like fetching the fields contained in a structure.

When using a parentId parameter, the API will fetch objects contained in the designated parent only.

cURL request using parentId

curl -L -X GET 'https://yourapi.datagalaxy.com/v2/fields?versionId=913f3fbb-6d87-49b8-9428-1cea07e25351&parentId=0596ec5a-6e36-4476-8875-e76bf1f538b0:1848eaf4-31d2-4de1-8acf-64f7a2eeeb29' -H 'Authorization: Bearer {token}'

includeAttributes - add object attributes to result

The includeAttributes parameter is a boolean you can add as queryString in your API request.
It will retrieve the attributes of each object fetched and display them in the attributes property.

cURL request using includeAttributes

curl -L -X GET 'https://yourapi.datagalaxy.com/v2/fields?versionId=913f3fbb-6d87-49b8-9428-1cea07e25351&includeAttributes=true' -H 'Authorization: Bearer {token}'

Response payload

{
    ...
    "results": [
        {
            "id": "0596ec5a-6e36-4476-8875-e76bf1f538b0:1848eaf4-31d2-4de1-8acf-64f7a2eeeb29",
            "name": "ADDRESS",
            "type": "Column",
            ...
            "attributes": {
                "status": "Proposed",
                "tableTechnicalName": "CLIENT",
                "tableDisplayName": "CLIENT",
                "tags": [],
                "summary": "",
                "description": "",
                "technicalComments": "",
                "dataTypePrecisionSize": null,
                "isMandatory": false,
                "isPrimaryKey": false,
                "isForeignKey": false,
                "isTechnicalData": false,
                "owners": [
                    "john.smith@datagalaxy.com"
                ],
                "stewards": [
                    "john.smith@datagalaxy.com"
                ],
                "size": 50,
                "columnDataType": "VariableString",
                "creationTime": "2022-07-25T15:41:47.235+00:00",
                "lastModificationTime": "2022-07-25T15:41:47.235+00:00",
                "order": 1
            },
            ...
        },
        ...
    ]
}

includeLinks - add objects links to the result

In some cases, you might want to get the links of each object you fetch.

The includeLinks parameter adds a links property to the objects returned in the response payload.
This property contains, for each existing link, the target's object information.

cURL request using includeLinks

curl -L -X GET 'https://yourapi.datagalaxy.com/v2/fields?versionId=913f3fbb-6d87-49b8-9428-1cea07e25351&includeLinks=true' -H 'Authorization: Bearer {token}'

Response payload

{
    ...
    "results": [
        {
            "id": "0596ec5a-6e36-4476-8875-e76bf1f538b0:380582ac-bb74-4698-91dc-2f24347e3892",
            "name": "ADRESSE",
            "type": "Column",
            ...
            "links": {
                "IsInputOf": [
                    {
                        "id": "0596ec5a-6e36-4476-8875-e76bf1f538b0:72ba294f-1922-4b55-b455-1f06db94390e",
                        "name": "Process",
                        "technicalName": "Process",
                        "type": "DataProcessing",
                        "path": "\\Process",
                        "typePath": "\\DataProcessing",
                        "dataType": "DataProcessing",
                        "location": "dataProcessing/913f3fbb-6d87-49b8-9428-1cea07e25351/0596ec5a-6e36-4476-8875-e76bf1f538b0:72ba294f-1922-4b55-b455-1f06db94390e"
                    }
                ]
            },
            ...
        },
        ...
    ]
}