Introduction

This documentation describes the individual categories of resources you can use to manipulate objects in GoodData.CN.

Foreword

GoodData.CN public API is divided to three major categories with its own URI space and set of unique properties. Not having one unique style across all API have one good reason - serving specific purpose fitting specific use-case.

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

We’re aware of the fact that not all APIs in these categories are fully RESTful¹ (in fact only the Entity API interface fully conforms to the constraints of REST architectural style) and there’s a good reason for that - usability. There is no strong reason for making Declarative API Interface changing or reading state of several resources in one operation or RPC API Interface not changing any persistent resource fully RESTful. Main design principle was to have intuitive and performant APIs consistent within its own category.

Entity API Interface

The Entity API interface are interconnected resources representing application state. API design fully conforms RESTful principles and taking advantage of hypermedia, http caching or easy discovery of resources. More over there’s advanced support for filtering and querying by entity fields for collection resources, uniform paging and support for compound documents².

Format

Format of the Entity API Interface is based on JSON:API specification with some minor differences in form of missing some special features like sparse fieldset or vendor specific implementation of others (default relationships payload, filtering, etc.). Because of that the vendor specific media type is used for Entity API Interface.

From the client perspective the Entity API interface is state machine that can be manipulated and allows accessing and managing resources one by one when all of them are linked with hypertext. It is the main difference to the Declarative API Interface which works with a model specified in an all-in-one document only.

Most of the entities are exposing CRUD interface, some of them only Read (where updates can be done by Declarative API Interface only).

Identifiers

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

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

To see more examples check Workspace Object Identification.

URI Path

• All resources conforming Entity API Interface are located under .../api/entities/* path.

Media type

• The media type is application/vnd.gooddata.api+json.
• It is extension of JSON media inspired by JSON::API.

Declarative API Interface

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

• All available endpoints/components support two HTTP methods, the GET and the PUT.
• You can use the GET method to back up the component before putting a new content.
• You can use an empty boilerplate (core structure without objects) to clean the component completely (see examples).
• Note that (in compare to Entity API interface) PUT HTTP method never return payload (to save some bytes send over the wire and fact that what payload is sent it should be also returned).

Format

The payload do not contain any specific meta-fields (in compare to Entity API interface) in order to save some bytes send over the wire and fact that entities in one Declarative resource do not reference any other declarative resource.

Identifiers

Each object in declarative payload contains unique id. Uniques of specific object is combination of its type (deducted from context - name of the json wrapper node) and id.

Example of Workspace Data Filter with id ‘unique_id_122’:

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

For referencing other objects - establishing relationship - the identifier with id & type must be used:

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

URI Path

• All Declarative resources are located under .../api/layout/* path.

Media type

• The media type is application/json.

RPC API Interface

Simply said this category represents actions - RPC³ over JSON API. In scope of GoodData.CN API public Actions are operations which typically are not changing internal state of resources. Most common use-case is start some form of process (POST HTTP method) where result can be later retrieved ( GET HTTP method - depends on specific resource if synchronously or asynchronously).

URI Path

• Whole “Actions” API-space is located under .../api/actions/* path and further divided to:

Executions

• Related to “computational” part of application.
• Example - running execution of AFM - .../api/actions/workspaces/{wsId}/execution/afm/execute or computing valid objects - .../api/actions/workspaces/{wsId}/execution/afm/computeValidObjects

DataSources

• Operations on top of data source.
• Example - scanning - .../api/actions/dataSources/{dataSourceId}/scanModel or testing - .../api/actions/dataSources/{dataSourceId}/test Data Source

Media type

• The media type is application/json.