API Documentation

The GoodData.CN API is a core part of GoodData.CN. With the GoodData.CN API, you can integrate all of the features of GoodData.CN into your own application. Alternatively, you can browse through the data and actions of GoodData.CN by using any application capable of sending HTTP requests.

Foreword

The GoodData.CN public API is divided into three major categories. Each category has its own URI space and unique set of properties. Dividing the API into multiple categories helps ensure that the APIs are identifiable for their particular use case.

• Entity API Interface
• Declarative API Interface
• RPC API Interface

We’re aware that not all of the APIs in these categories meet the requirements to be RESTful¹. In fact, only the entity API interface fully conforms to the constraints of the REST architectural style. There was no strong reason to adhere to the REST architecture to make the declarative API interface change or read the state of several resources in one operation. Nor was there a strong reason to fully adhere to RESTful architecture to make sure the RPC API interface doesn’t change persistent resources. We chose this approach to help make the API intuitive and consistent according to its category and use case.

Entity API Interface

The entity API interface is composed of interconnected resources that represent the application state. The API design fully conforms to RESTful principles to take advantage of hypermedia, HTTP caching, and easy resource discovery. There is also advanced support for filtering and querying by entity fields for collection resources, as well as support for uniform paging and support for compound documents².

Format

The format of the entity API interface is based on the JSON:API specification. Our implementation does not include special features such as sparse fieldsets. However, we do use vendor specific implementations of other features (default relationships payload, filtering, and etc.). Because we have our own implementation of several features, the vendor specific media type is used for the entity API interface.

From the client perspective, the entity API interface is a state machine that can be manipulated and managed by accessing resources one-by-one when all of them are linked with hypertext. This is the main difference between the entity API interface and the declarative API interface which works with the model specified in the all-in-one document only.

Most of the entities are exposing a CRUD interface, and some of them are Read only (where updates can be done by declarative API interface.

Identifiers

Every object is identified by two items [type, id] similarly to JSON:API:

• Type represents the particular category of an object (dataSource for Data Source, workspace for Workspace and so on)
• Id is the logical name of an object instance. It is limited to the 255 characters of a-Z0-9._-.
  • Id can be prefixed by workspace if referenced from another (inherited) workspace - workspace:id
  • In the case of grain/reference, it can contain id like parent:id

To see more examples, see Workspace Object Identification.

URI Path

The path for all resources conforming to the entity API interface is located under .../api/entities/*.

Media Type

The media type is application/vnd.gooddata.api+json. This is a vendor specific extension of JSON media inspired by JSON::API.

Declarative API Interface

The declarative interface works with the model specified in the all-in-one document only. This is the main difference between the the declarative API interface and the entity API interface which allows accessing and managing objects one by one.

• All available endpoints/components support two HTTP methods: GET and PUT.
• You can use the GET method to back up the component before you PUT a new definition.
• You can use an empty template to clean the component completely (see examples).
• To save a few bytes of data, the PUT HTTP method never returns the payload.

Format

The payload does not contain any specific meta-fields as entities in one declarative resource do not reference any other declarative resources.

Identifiers

Each object in the declarative payload contains a unique id. The unique instances of a specific object are named with a combination of its type from the context of the JSON wrapper node and an id.

Example of Workspace Data Filter with id ‘unique_id_122’:

{
  "workspaceDataFilters": [
    {
      "id": "unique_id_122",
      ...
   },
    ...
  ]
}

For referencing other objects, the identifier with id & type must be used:

{ 
  "identifier" :
  {
    "id" : STRING,
    "type" : "workspace"|"analyticalDashboard"|...,
   }
}

URI Path

• The path for all declarative resources is located under .../api/layout/*.

Media Type

• The media type is application/json.

RPC API Interface

This category represents actions, for example - RPC³ over JSON API. In the scope of the GoodData.CN API, public Actions are operations which typically do not change the internal state of resources. The most common use-case is to start a process (for example, the POST HTTP method) where the result can be later retrieved (for example, the GET HTTP method depending on if a specific resource is used synchronously or asynchronously).

URI Path

• The path for the RPC API interface is located under .../api/actions/* and it is further divided into the following components:

Executions

• Related to the “computational” part of the application. For example, the running execution of AFM (attributes, filters, measures) - .../api/actions/workspaces/{wsId}/execution/afm/execute or computing valid objects - .../api/actions/workspaces/{wsId}/execution/afm/computeValidObjects

DataSources

• Operations on top of a data source. For example, scanning - .../api/actions/dataSources/{dataSourceId}/scan or testing - .../api/actions/dataSources/{dataSourceId}/test Data Sources.

Media Type

• The media type is application/json.