First Steps With APIs

Best way to get started with GoodData is to utilize the free GoodData Cloud Trial. So in this article, we will go over the whole process from creating a GoodData Trial to sending your first API request.

There are no requirements to get started with our APIs, and that’s the beauty of it!

Before we start, ensure that:

You have a GoodData Cloud Trial account
You have an API token to access the APIs

When you are done, simply export your GD_TOKEN to your environment:

export GD_TOKEN=$(your_token)

Token persistence

Note, this does not persist the token, so you will have to do this every time you open a new terminal. Alternatively you can add this line to your .bashrc or .zshrc file.

Send Your First API Request

One of the easiest and most visible use-cases for the APIs is to change the localization of your GoodData UI.

In this example we will change the localization of your GoodData UI to French. To do that, we will use the Organization Settings API.

First, we need to create the locale settings. To do that, we will send a POST request to the /api/v1/entities/organizationSettings endpoint with the following payload:

{
    "data":
    {
        "type": "organizationSetting",
        "id": "locale",
        "attributes": {
            "content": {"value": "{fr-FR}"}
        }
    }
}

organizationSetting format

Note that the id of the organization setting is locale and the value is {fr-FR}. This format is the same for all organization settings, e.g. White-Labeling, Timezone, Date Format and much more.

Here is the full request:


curl $ENDPOINT/api/v1/entities/organizationSettings \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer $(GD_TOKEN)" \
  -X POST \
  -d '{
    "data":
    {
        "type": "organizationSetting",
        "id": "locale",
        "attributes": {
            "content": {"value": "{fr-FR}"}
        }
    }
}' | jq .

The response should look like this:

{
  "data": {
    "type": "organizationSetting",
    "id": "locale",
    "attributes": {
      "content": {
        "value": "{fr-FR}"
      }
    }
  }
}

Now, if you open your GoodData UI, you should see that the UI is in French.

Localized parts of the UI

Note, that only Dashboards, Analytical Designer and the Metric Editor are localized. The rest of the UI is in English.

Now we can call /api/v1/entities/organizationSettings/locale, because we have created the locale settings.

So to enable a different language, simply call the /api/v1/entities/organizationSettings/locale endpoint with the following PUT request:

curl $ENDPOINT/api/v1/entities/organizationSettings/locale \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer $(GD_TOKEN)" \
  -X PUT \
  -d '{
    "data":
    {
        "type": "organizationSetting",
        "id": "locale",
        "attributes": {
            "content": {"value": "$(LANGUAGE_ID)"}
        }
    }
}' | jq .

We understand, that you might not speak French. To switch back, just send the PUT request with the LANGUAGE_ID set to en-US(default):


curl $ENDPOINT/api/v1/entities/organizationSettings \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer $(GD_TOKEN)" \
  -X PUT \
  -d '{
    "data":
    {
        "type": "organizationSetting",
        "id": "locale",
        "attributes": {
            "content": {"value": "{en-US}"}
        }
    }
}' | jq .

To learn more about the localization, check out our Change Display Language article.

Authentication