Workspace Entity API Interface

Entity API

Check high-level overview of the Entity API interface first.

There are differences against JSON:API

• Object identification involves next to the type and id a space identifier where the object belongs when working or referencing objects not originating in the working workspace.
• Payload does not include the part relationships by default but upon an explicit query parameter include that also extends payload by content of related objects.
  • Mind difference of availability of references in logical and analytics objects. Analytics objects use free-form content (except metrics) so all references are always present here (in maql for metrics) while missing the part relationships. In logical objects there is no such a content and client must use the parameter “include” to reveal them.

API Documentation

The entity interface is available under the /api/v1/entities/workspaces/<workspace-id>/<type>/... resource.

To see the entire API specification, visit API reference.

Examples

First, be aware of your application endpoint. For Helm Chart deployment, it represents the https://<organization-hostname> value. For All-in-One docker image, the default endpoint is http://localhost:3000.

In the following examples:

• the endpoint is substituted by $HOST_URL variable;
• the workspace identifier (name) used here is workspace.

Create new object

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -X POST \
  -d '{ "data": { "id": "visobj-1", "type": "visualizationObject", "attributes" : { "title": "First visual", "description": "", "content": {} } } }' \
  $HOST_URL/api/v1/entities/workspaces/workspace/visualizationObjects

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -X POST \
  -d '{ "data": { "id": "metric-1", "type": "metric", "attributes" : { "title": "First metric", "description": "", "content": { "maql": "SELECT SUM(1)" } } } }' \
  $HOST_URL/api/v1/entities/workspaces/workspace/metrics

Update on existing object, modify title

assuming in the metadata exists object of type visualizationObject with id “visobj-1”

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -X PUT \
  -d '{ "data": { "id": "visobj-1", "type": "visualizationObject", "attributes" : { "title": "Fresh visual", "description": "", "content": {} } } }' \
  $HOST_URL/api/v1/entities/workspaces/workspace/visualizationObjects/visobj-1

Delete an existing object

assuming in the metadata exists object of type visualizationObject with id “visobj-1”

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -X DELETE \
  $HOST_URL/api/v1/entities/workspaces/workspace/visualizationObjects/visobj-1