First Steps With APIs

There are no requirements to get started with our APIs. However, the best way how to test them is to use the free GoodData Cloud Trial. In this article, we will go over the whole process from creating a GoodData Trial to sending your first API request.

First, ensure that you have:

An active GoodData Cloud Trial account
A valid API token

Then export your GD_TOKEN to your environment:

export GD_TOKEN=$(your_token)

Token persistence

Exporting the token does not make it persistent. You can add the command above to your .bashrc or .zshrc file, or you can manually run the command when you open a new terminal.

Send Your First API Request

One of the simplest and most visible uses of APIs is changing the localization of your GoodData UI.

For example, change your GoodData UI to French. To do that, use the Organization Settings API.

First, create the locale settings. 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, etc.

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}"
      }
    }
  }
}

Your GoodData UI is now in French.

Localized parts of the UI

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

Because you have created the locale settings in the previous step, you can now call the /api/v1/entities/organizationSettings/locale endpoint. To enable a different language, call this 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 .

To switch back to English, send a PUT request with LANGUAGE_ID set to en-US:


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, see the Change Display Language article.

Authentication