API Conventions

General Conventions

API endpoints start with /api
The API protocol is HTTPS
Use camelCase for entities, URI paths, and query parameter names

Paging

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

Collection resources support paging. The behavior of paging can be changed 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 apply filters to your API requests. This refines the results, therefore lowers the volume of data transferred between the backend and your application.

GoodData uses 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 the filter URI parameter:

.../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

Return 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 the complete list of supported operators below.

Operators

Logical Operators

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

Logical AND: and or ;
Returns entities with a specified title and the ‘Sales’ tag. 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: ==
Returns entities with the ‘Sales’ tag:
```
filter=tags==Sales
```
Not equal to: !=
Returns entities without the ‘Sales’ tag:
```
filter=tags!=Sales
```
In: =in=
Returns entities with at least one of the specified tags (‘PreSales’ or ‘PostSales’):
```
filter=tags=in=(PreSales,PostSales)
```
See grouping.
Not in: =out=
Returns entities without the specified tags (‘PreSales’ or ‘PostSales’):
```
filter=tags=out=(PreSales,PostSales)
```
See grouping.
Case-sensitive contains: =contains=
Returns entities with a tag containing the ‘Sales’ substring:
```
filter=tags=contains=Sales
```
Case-insensitive contains: =containsic=
Returns entities with a tag containing the ‘sales’ substring, regardless of whether the substring is upper-case or lower-case:
```
filter=tags=containsic=sales
```
Pattern search: =like=
Returns entities with a tag starting with the letter ‘P’ and ending with the ‘Sales’ substring:
```
filter=tags=like=P*Sales
```
- * to capture a group of characters
- ? to capture exactly one character
Is null: =isnull=
Returns 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

Returns only the visualizationObjects related to metrics with the ‘quantities’ title:

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

Grouping

To create a list or group of items to filter, use the 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

Its possible values are:

ALL returns entity definitions from the {workspaceId} workspace and from its parent workspaces (default behavior)
PARENTS returns entity definitions only from the parent workspaces
NATIVE returns entity definitions only 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