Workspace Entity API Interface

Before diving in, we recommend reading the overview of the Entity API interface.

Key Differences from JSON:API

• Object Identification: In addition to the type and ID, objects include a space identifier that shows which space the object belongs to. This is useful when working with or referencing objects that do not come from the current workspace.
• Payload Relationships: By default, the payload does not include the relationships parameter. To include relationships, you must use the include query parameter, which adds related objects’ content to the payload.
  • References in Objects: For analytics objects, references are always defined in the content parameter (except for metrics, which use maql). For logical objects, there is no content by default, so you need to use the include parameter to see them.

API Documentation

The Entity API is available at:

/api/v1/entities/workspaces/<workspace-id>/<type>/...

For the full API specification, see the API reference guide.

Examples

Make sure you know your application endpoint.

• For Helm Chart deployments, the endpoint will be https://<organization-hostname>.
• For All-in-One Docker images, the default endpoint is http://localhost:3000.

In the examples below:

• $HOST_URL represents the endpoint.
• The workspace identifier used here is workspace.

Create a New Object

To create a new visualization object or metric:

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 an Existing Object

To update the title of an existing visualization object (e.g., 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

To delete an existing visualization object (e.g., 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