API

One of the main strengths of the GoodData platform is its APIs. Through GoodData APIs you can access the raw data, customize your user interface, and more. Essentially, they allow you to incorporate all of GoodData’s features into your own application. You can also explore your data through the functionality of GoodData using any application that can send HTTP requests.

Introduction

The GoodData public API is divided into three main categories, each with its own unique URI space and set of features. This division allows users to easily identify the right API for their specific needs.

The three main API categories are:

Entity API
Declarative API
Action API

Together, the three main components let you access and manage most of the GoodData platform’s features.

Entity API

The Entity API is a vital component of the GoodData platform, designed to comply with RESTful principles for enhanced hypermedia, HTTP caching, and resource discovery. This API employs interconnected resources representing the application state, offering advanced support for filtering, querying, and uniform paging.

The Entity API supports CRUD operations on most entities, and all objects are identified by a combination of their type and a unique id. Users can navigate and manipulate the Entity API as a state machine by accessing resources through hypertext.

Example endpoints:

../api/v1/entities/dataSources
../api/v1/entities/workspaces/{workspaceId}/workspaceSettings
../api/v1/entities/admin/organizations/{id}

Entity API endpoints use the application/vnd.gooddata.api+json as a media type, which is a vendor-specific extension of JSON media inspired by JSON::API.

Custom JSON:API Implementation

GoodData’s JSON:API implementation differs from the standard version, including the exclusion of part relationships by default, limited support for expanding related objects with the include query parameter, and the absence of sparse fieldsets.

Additionally, while the PUT HTTP method updates mutable resources, the PATCH method only supports updates without modifying relationships.

Example

This example shows how to create a Snowflake data source using the Entity API.

curl $ENDPOINT/api/v1/entities/dataSources \
  -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": "dataSource",
    "id": "<unique_id_for_the_data_source>",
    "attributes": {
      "name": "<data_source_display_name>",
      "url": "jdbc:snowflake://<SNOWFLAKE_ACCOUNT>.snowflakecomputing.com:5432?warehouse=<SNOWFLAKE_WAREHOUSE>&db=<SNOWFLAKE_DBNAME>",
      "schema": "<SNOWFLAKE_SCHEMA>",
      "type": "SNOWFLAKE",
      "username": "<SNOWFLAKE_USER>",
      "password": "<SNOWFLAKE_PASSWORD>"
    }
    }
  }' | jq .

Declarative API

The Declarative API operates exclusively with the all-in-one document model, which distinguishes it from the Entity API that allows individual object access and management. This is especially useful if you need to work with all the objects at once, typically updating them at the same time or removing them from a workspace.

The Declarative API supports both the GET and PUT HTTP methods for all available endpoints and components, enabling users to back up a component before updating it or even completely clear it using an empty template. The PUT method does not return a payload to save data.

Example endpoints:

../api/v1/layout/organization
../api/v1/layout/workspaces/{workspaceId}/dashboards
../api/v1/layout/workspaces/{workspaceId}/logicalModel

The payload format does not contain specific meta-fields. Each object has a unique id in combination with a type from the JSON wrapper node. The media type for Declarative API is application/json.

Example

The following example sets all the workspaces data filters as a bulk replacement using Declarative API.

curl $ENDPOINT/api/v1/layout/workspaceDataFilters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -d '{
  "workspaceDataFilters": [
    {
      "columnName": "WDF__CLIENT_ID",
      "id": "WDF__CLIENT_ID",
      "title": "Client id",
      "workspace": {
        "id": "ecommerce-parent",
        "type": "workspace"
      },
      "workspaceDataFilterSettings": [
        {
          "filterValues": [
            "merchant__bigboxretailer"
          ],
          "id": "ecommerce-merchant-bigboxretailer",
          "title": "ecommerce merchant bigboxretailer",
          "workspace": {
            "id": "ecommerce-merchant-bigboxretailer",
            "type": "workspace"
          }
        },
        ...
        }
      ]
    },
    {
      "columnName": "PRODUCT_BRAND",
      "id": "PRODUCT_BRAND",
      "title": "Product Split",
      "workspace": {
        "id": "ecommerce-parent",
        "type": "workspace"
      },
      "workspaceDataFilterSettings": [
        ...
      ]
    }
  ]
}' \
  -X PUT | jq .

Action API

The Action API represents action-based operations within the GoodData platform, such as Remote Procedure Call (RPC) over JSON API.

Most of the Action calls do not change the state of the application. Instead, they usually return the result of an operation. For example, /api/v1/actions/workspaces/{workspaceId}/execution/afm/computeValidObjects returns a list of valid objects for the given workspace.

Example endpoints:

../api/v1/actions/dataSources/{dataSourceId}/test
../api/v1/actions/workspaces/{workspaceId}/execution/afm/computeValidObjects
..api/v1/actions/dataSources/{dataSourceId}/uploadNotification

The Action API includes components related to the computational aspect of the application, as well as operations on data sources. The Action API media type is application/json.

Example

The following example shows how to test a data source using the Action API.

curl $ENDPOINT/api/v1/actions/dataSources/<dataSourceId>/test \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {GD_TOKEN}" \
  -d '{}' \
  -X POST | jq .

First Steps