API Conventions

General Conventions

API endpoints start with /api
APIs protocol: HTTPS
camelCase for entities, URI paths, and query parameter names

Paging

Collections (resource lists) use plural form (e.g. workspaces).

Collection resources support paging. The behavior of paging can be altered by the following query parameters:

size
The number of objects to be returned. The default is 20.
page
Specifies which pagination index will be returned in a collection set. The index starts at 0.

Filtering

You can filter the results of your API requests to refine the set of entities you want to obtain and limit the volume of data transferred between the backend and your application.

GoodData utilizes RSQL to define filters on the entities API. Only a subset of RSQL is supported, and we add our operators to make some queries easier.

Filter

Filter the API call result using URI parameter filter as follows:

.../api/v1/entities/...[?&]filter=<RSQL>

where <RSQL> is the RSQL query consisting of <property><operator><arguments>;:

property is an attribute of the queried entity
operator is one of the supported logical or comparison operators
argument represents the filtered value in form related to comparison operator

Example

Fetch only visualizationObjects that use a metric with the word ‘sale’ in the metrics title:

.../api/v1/entities/workspaces/{workspaceId}/visualizationObjects?filter=metrics.title=containsic='sale';

Case-sensitivity

This example uses the containsic operator which is the case-insensitive variation of the contains operator. See below for a complete list of supported operators.

Operators

Logical Operators

To filter for multiple properties at the same time, use the AND logical operator:

Logical AND: and or ;
Filter entities with specified title and tag ‘Sales’. Using the and operator and url encoded value:
```
filter=title=like=*date+and+tags==Sales
```
or using the ; operator:
```
filter=title=like=*date;tags==Sales
```

Available RSQL Comparison Operators:

Equal to: ==
Filter entities having tag ‘Sales’:
```
filter=tags==Sales
```
Not equal to: !=
Filter entities not having tag ‘Sales’:
```
filter=tags!=Sales
```
In: =in=
Filter entities having one of the specified tags ‘PreSales’ or ‘PostSales’:
```
filter=tags=in=(PreSales,PostSales)
```
See grouping.
Not in: =out=
Filter entities having one of the specified tags ‘PreSales’ or ‘PostSales’:
```
filter=tags=out=(PreSales,PostSales)
```
See grouping.
Case-sensitive contains: =contains=
Filter entities having a tag containing a substring ‘Sales’:
```
filter=tags=contains=Sales
```
Case-insensitive contains: =containsic=
Filter entities having a tag containing a substring ‘sales’ regardless on the case sensitivity:
```
filter=tags=containsic=sales
```
Pattern search: =like=
Filter entities having a tag starting with letter ‘P’ and ending with substring ‘Sales’
```
filter=tags=like=P*Sales
```
- * to capture a group of characters
- ? to capture exactly one character
Is null: =isnull=
Filter entities where some field is null:
```
filter=someField=isnull=true
```
- true to capture fields that are null
- false to capture fields that are not null

Filtering Using Relationships

You can filter by a property from a referenced entity in case two entities are in a relationship. You have to specify the relationship property before the property you are going to filter (an extended form of the property): <relationship-property-name>.<property-of-related-entity>

Example

Filter only visualizationObjects having relation to metrics with a title ‘quantities’:

.../api/v1/entities/workspaces/{workspaceId}/visualizationObjects?filter=metrics.title==quantities

Grouping

To create a list / group of items to filter use grouping operator () and separate items with , or or - for example (PreSales,PostSales) or (PreSales or PostSales).

Origin

By default the api/v1/entities/workspaces/{workspaceId}/... API endpoints return entity definitions from the {workspaceId} workspace, as well as any parent workspaces the {workspaceId} may have. You can control this behaviour using the origin URI parameter:

.../api/v1/entities/...[?&]origin=ALL|PARENTS|NATIVE

where:

ALL returns entity definitions from the {workspaceId} workspace and from its parent workspaces (default behaviour)
PARENTS only returns entity definitions from the parent workspaces
NATIVE only returns entity definitions from the {workspaceId} workspace

Example

Fetch only visualizationObjects that use a metric with the word ‘sale’ in the metrics title and fetch visualizationObjects only from the {workspaceId} workspace itself, none from its parent workspaces:

.../api/v1/entities/workspaces/{workspaceId}/visualizationObjects?filter=metrics.title=containsic='sale'&origin=NATIVE;

Limitations

The following limitations apply to the filtering of API requests:

You can filter only results of the entities APIs /api/v1/entities/.... Declarative APIs do not support filtering.
Ensure the filtered string is properly url encoded. For example, wrap values containing a whitespace character with single or doubles quotes and apply url encoding to the entire value.
Queries are case-sensitive in general. There are GoodData specific operators allowing case-insensitive queries.

Authentication

Errors