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:

Then export your GD_TOKEN to your environment:

export GD_TOKEN=$(your_token)

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

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.

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.