GoodData API Documentation

The GoodData API is based on REST principles, all you need to use it is your GoodData account. You must be authenticated and call HTTPs requests on the URLs listed below. This documentation covers the core resources you can used to manipulate objects on the GoodData Platform. Review the information basic instructions if you are new to APIs.

Note: Use your GoodData TESTING credentials for API calls. Please do not use your production credentials.

Allowed HTTPs requests:

  • POST - Creates or updates a resource

  • PUT - Updates a resource

  • GET - Retrieves a resource or list of resources

  • DELETE - Delete a resource

Typical Server Responses

  • 200 OK - The request was successful (some API calls may return 201 instead).

  • 201 Created - The request was successful and a resource was created.

  • 204 No Content - The request was successful but there is no representation to return (that is, the response is empty).

  • 400 Bad Request - The request could not be understood or was missing required parameters.

  • 401 Unauthorized - Authentication failed or user does not have permissions for the requested operation.

  • 403 Forbidden - Access denied.

  • 404 Not Found - Resource was not found.

  • 405 Method Not Allowed - Requested method is not supported for the specified resource.

  • 429 Too Many Requests - Exceeded GoodData API limits. Pause requests, wait one minute, and try again.

  • 503 Service Unavailable - The service is temporary unavailable (e.g. scheduled Platform Maintenance). Try again later.

Platform Availability

If The GoodData Platform is in scheduled maintenance, REST API Returns a 503 error code and following message is displayed in the response body:

Scheduled maintenance in progress. Please try again later.

Otherwise it will return 503 with a descriptive error message. Specific errors messages are listed with individual APIs. You can use gdc/ping resource to check the Platform availability.

GET

/gdc/ping

Checks Platform availability.

Response

204 (No Content)

Response

503 (Service Unavailable)
Scheduled maintenance in progress. Please try again later.  

Response

503 (Service Unavailable)
Content-Type: application/json
{"error":{
    "message": "Internal server error. Please fill in bug report with request_id='{error-id}'"
}}

Log In

GoodData authentication uses two kinds of tokens to track user sessions:

  • A long-lived SST token, which you obtain when you call /gdc/account/login

  • A short-lived TT token, which you obtain when you call gdc/account/token using your SST Token. This token is encrypted, and is quickly verified by the resource servers.

Steps:

  1. POST your credentials to the login resource. The SST token is returned in the SetCookie header.

  2. GET the token resource, and include the SST token in your header. The TT token is returned in the SetCookie header.
    You are now authenticated. Include this TT token in a -cookie header on all API calls.

Note: The TT token has limited validity. If you received a 401 Unauthorized Response, GET a new TT token.

Additional Information

You can use two methods to obtain and use tokens: HTTP Cookies and custom headers. These methods are controlled by verify_level property when you log in. The advantage of using Cookies is that most client libraries are able to use them automatically without a need to write custom code (store and send them with the followup API requests based on the URI path).

  • Do not specify a verify_level if you intend to rely on cookie usage. You cannot use this method across domains, and therefore not in the data staging area.

  • Specify a verify_level of 2 if your client uploads data. You will get the token values after you log in and token resources and you'll need to set the X-GDC-AuthSST and X-GDC-AuthTT headers to appropriate token values whenever they are required.

POST

/gdc/account/login

Log in.

Parameters
Name Description Details
login

GoodData login email address

string, required
password

GoodData password

string, required
remember

Specifies whether to remember login credentials.

boolean, required
verify_level

Verification level of the token. Specify '0' for HTTP cookies; specify '2' for custom HTTP headers

integer, optional

Response

200 (OK)
Content-Type: application/json
Set-Cookie: GDCAuthTT=; path=/gdc; expires=Mon, 30-Jul-2012 09:12:42 GMT; secure; HttpOnly, GDCAuthSST={super-secured-token}; path=/gdc/account; secure; HttpOnly
{
    "userLogin":{
        "profile":"/gdc/account/profile/{user-id}",
        "state":"/gdc/account/login/{user-id}"
    }
}

GET

/gdc/account/token

Request a TT token.

Response

200 (OK)
Set-Cookie: set-cookie: GDCAuthTT={temporary-token}; path=/gdc; expires=Mon, 30-Jul-2012 09:12:42 GMT; secure; HttpOnly, GDCAuthSST={super-secured-token}; path=/gdc/account; secure; HttpOnly

GET

/gdc/account/profile/{user-id}

Retrieves details of your user account, including email addresses, phone number, and authentication provider. This information is also returned after successful authentication.

Response

200 (OK)
  {
     "accountSetting" : {
       "country" : "cz",
       "firstName" : "Name",
       "ssoProvider" : null,
       "timezone" : null,
       "position" : "",
       "authenticationModes" : [],
       "companyName" : "GoodData",
       "login" : "email@gooddata.com",
       "email" : "email@gooddata.com",
       "created" : "2011-08-10 08:37:46",
       "updated" : "2014-04-11 01:18:07",
       "lastName" : "Lastname",
       "phoneNumber" : "7755441225",
        "links" : {
            "self" : "/gdc/account/profile/{profile-id}",
            "projects" : "/gdc/account/profile/{profile-id}/projects"
                  }
            }
    }

DELETE

/gdc/account/login/{user-id}

Log out.

Response

200 (OK)

Objects

Objects are the entities in the GoodData Platform. For example, Dashboards, Reports, Metrics, and Data Permissions are objects.

Object Creation

Create a New Object

POST

/gdc/md/{project-id}/obj{?createAndGet=true}

Create a new object. The example below creates a new metric.

Note: This example does not include the createAndGet parameter.

Response

200 (OK)
Content-Type: application/json
{
    "uri": "/gdc/md/{project-id}/obj/{object-id}"
}

Create and Retrieve a New Object

POST

/gdc/md/{project-id}/obj{?createAndGet=true}

Use this call to create new object. In this example you create a new metric and receive the complete object instead of link to it.

With the createAndGet=true parameter.

Response

200 (OK)
Content-Type: application/json
{
    "metric": {
        "content": {
            "format": "#,##0.00",
            "tree": {
                "content": [
                    {
                        "content": [
                            {
                                "value": "SUM",
                                "content": [
                                    {
                                        "value": "/gdc/md/{project-id}/obj/{object-id}",
                                        "position": {
                                            "column": 12,
                                            "line": 2
                                        },
                                        "type": "fact object"
                                    }
                                ],
                                "position": {
                                    "column": 8,
                                    "line": 2
                                },
                                "type": "function"
                            }
                        ],
                        "position": {
                            "column": 8,
                            "line": 2
                        },
                        "type": "expression"
                    }
                ],
                "position": {
                    "column": 1,
                    "line": 2
                },
                "type": "metric"
            },
            "expression": "SELECT SUM([/gdc/md/{project-id}/obj/{object-id}])"
        },
        "meta": {
            "author": "/gdc/account/profile/{user-id}",
            "uri": "/gdc/md/{project-id}/obj/{object-id}",
            "tags": "",
            "created": "2014-07-07 10:02:54",
            "identifier": "arFtGnK2gysS",
            "deprecated": "0",
            "summary": "",
            "unlisted": 1,
            "title": "My new metric",
            "category": "metric",
            "updated": "2014-07-07 10:02:54",
            "contributor": "/gdc/account/profile/{user-id}"
        }
    }
}

Existing Object Manipulation

Retrieve an Object

GET

/gdc/md/{project-id}/obj/{object-id}

Use this call to retrieve an object from the API.

Response

200 (OK)
Content-Type: application/json
{
    "metric": {
        "content": {
            "format": "#,##0.00",
            "tree": {
                "content": [
                    {
                        "content": [
                            {
                                "value": "SUM",
                                "content": [
                                    {
                                        "value": "/gdc/md/{project-id}/obj/{object-id}",
                                        "position": {
                                            "column": 12,
                                            "line": 2
                                        },
                                        "type": "fact object"
                                    }
                                ],
                                "position": {
                                    "column": 8,
                                    "line": 2
                                },
                                "type": "function"
                            }
                        ],
                        "position": {
                            "column": 8,
                            "line": 2
                        },
                        "type": "expression"
                    }
                ],
                "position": {
                    "column": 1,
                    "line": 2
                },
                "type": "metric"
            },
            "expression": "SELECT SUM([/gdc/md/{project-id}/obj/{object-id}])"
        },
        "meta": {
            "author": "/gdc/account/profile/{user-id}",
            "uri": "/gdc/md/{project-id}/obj/{object-id}",
            "tags": "",
            "created": "2014-07-07 09:50:49",
            "identifier": "adZtDDfkfAHG",
            "deprecated": "0",
            "summary": "",
            "unlisted": 1,
            "title": "My new metric",
            "category": "metric",
            "updated": "2014-07-07 09:50:49",
            "contributor": "/gdc/account/profile/{user-id}"
        }
    }
}

Update an Object

PUT

/gdc/md/{project-id}/obj/{object-id}

Use this call to update existing object. Use the full object body/content with your changes. See the example where we've changed the Metric definition (SUM -> AVG)

Response

200 (OK)
Content-Type: application/json
{
    "uri": "/gdc/md/{project-id}/obj/{object-id}"
}

Delete an Object

DELETE

/gdc/md/{project-id}/obj/{object-id}

Use this resource to delete specific objects.

Response

204 (No Content)

Project

Projects are one of the key objects in the GoodData platform. When working with GoodData, you basically create projects (datamarts). Metrics, Reports and Dashboards are then created inside Projects. The following two states are key for you and your integrations:

  • ENABLED - project is ready and available

  • DELETED - something is wrong

Once you create a Project with a POST request shown below, poll the returned url and check the Project state value until it is ENABLED or DELETED. Find out more information about how to create a project programatically on this discussion thread. Other states that project can be in:

  • PREPARING

  • LOADING

  • PREPARED

  • DISABLED

  • ARCHIVED

Project Properties

  • title (string) : Project Title

  • summary (string) : Project summary

  • roles (uri) : User's role in the Project

  • userPermissions (uri) : User permissions information

  • userRoles (uri) : User roles information

  • users (uri) : Project users information

  • created (date) : Date of project creation

  • updated (date) : Date of project update

  • author (uri) : Project creator account

  • exportUsers (boolean) : export users from project true/false

  • exportData (boolean) : export data from project true/false

  • token (string) : export Token for export/import project usage

POST

/gdc/projects

To create new project, use following call. Poll the resource that you received as response until it gives you the status: ENABLED or DELETED See the next API call for more details.

Response

201 (Created)
Content-Type: application/json
{
   "uri" : "/gdc/projects/{project-id}"
}

GET

/gdc/projects/{project-id}

To show the Project information after creation or whenever you need it. While creating a new project, poll this resource until the state is ENABLED or DELETED.

Response

200 (OK)
Content-Type: application/json
{
   "project" : {
      "content" : {
         "guidedNavigation" : "1",
         "isPublic" : "0",
         "state" : "ENABLED"
      },
      "links" : {
         "roles" : "/gdc/projects/{project-id}/roles",
         "ldm_thumbnail" : "/gdc/projects/{project-id}/ldm?thumbnail=1",
         "connectors" : "/gdc/projects/{project-id}/connectors",
         "self" : "/gdc/projects/{project-id}",
         "invitations" : "/gdc/projects/{project-id}/invitations",
         "users" : "/gdc/projects/{project-id}/users",
         "ldm" : "/gdc/projects/{project-id}/ldm",
         "publicartifacts" : "/gdc/projects/{project-id}/publicartifacts",
         "metadata" : "/gdc/md/{project-id}",
         "templates" : "/gdc/md/{project-id}/templates"
      },
      "meta" : {
         "created" : "2012-05-01 23:56:01",
         "summary" : "Project Summary",
         "updated" : "2012-05-01 23:56:01",
         "author" : "/gdc/account/profile/{user-id}",
         "title" : "Project Name",
         "contributor" : "/gdc/account/profile/{user-id}"
      }
   }
}

DELETE

/gdc/projects/{project-id}

This API call will DELETE your defined project. Only Project ADMIN can do this action.

Response

200 (OK)
Content-Type: application/json
{}

GET

/gdc/account/profile/{user-id}/projects

To list all existing projects

Response

200 (OK)
Content-Type: application/json
{
   "projects" : [
      {
         "project" : {
            "content" : {
               "guidedNavigation" : "1",
               "isPublic" : "0",
               "state" : "ENABLED"
            },
            "links" : {
               "roles" : "/gdc/projects/{project-id}/roles",
               "ldm_thumbnail" : "/gdc/projects/{project-id}/ldm?thumbnail=1",
               "userPermissions" : "/gdc/projects/{project-id}/users/{user-id}/permissions",
               "userRoles" : "/gdc/projects/{project-id}/users/{user-id}/roles",
               "connectors" : "/gdc/projects/{project-id}/connectors",
               "self" : "/gdc/projects/{project-id}",
               "invitations" : "/gdc/projects/{project-id}/invitations",
               "users" : "/gdc/projects/{project-id}/users",
               "ldm" : "/gdc/projects/{project-id}/ldm",
               "metadata" : "/gdc/md/{project-id}",
               "publicartifacts" : "/gdc/projects/{project-id}/publicartifacts",
               "templates" : "/gdc/md/{project-id}/templates"
            },
            "meta" : {
               "created" : "YYYY-MM-DD HH:MM:SS",
               "summary" : "Project Summary",
               "updated" : "YYYY-MM-DD HH:MM:SS",
               "author" : "/gdc/account/profile/{user-id}",
               "title" : "Project Name",
               "contributor" : "/gdc/account/profile/{user-id}"
            }
         }
      } ]
}

Export a complete project

Export a complete project

POST

/gdc/md/{project_id}/maintenance/export

  • exportUsers (required, boolean) - Specifies whether to include users in the export.
    Default: 1

  • exportData (required, boolean) - Specifies whether to include project data in the export.
    Default: 1

  • authorizedUsers (optional, string) - Comma-separated list of email addresses of users authorized to import the project. Surround email addresses with double quotes.

  • excludeSchedule (optional, boolean) - Specifies whether to include scheduled Emails in the export. All schedules you import to a project are enabled, even if they were disabled when exported.
    Default: 0

Response

  • status (uri) - URI where you can poll for the status of the export.

  • token (string) - Token to use to import the exported metadata.

Parameters
Name Description Details
project_id

The ID of the project you want to export.

string, required

Response

200 (OK)
Content-Type: application/json
{
   "exportArtifact" : {
      "status" : {
         "uri" : "/gdc/md/{project_id}/etltask/{task_id}"
      },
      "token" : "EXPORT_TOKEN"
   }
}

Import a complete project

Import a complete project

POST

/gdc/md/{project_id}/maintenance/import

  • token (required, string) - Token to use to import the exported metadata. This token is created during export.

NOTE: All schedules you import to a project are enabled, even if they were disabled when exported.

Default: 0

Parameters
Name Description Details
project_id

The ID of the project where you want to import the project token.

string, required

Response

200 (OK)
Content-Type: application/json
{
"uri" : "/gdc/md/{project_id}/etltask/{task_id}"
}

PUT

/gdc/projects/{project-id}/styleSettings

To create your own custom colour palette in given Project

Response

204 (No Content)

GET

/gdc/projects/{project-id}/styleSettings

To GET your current color palette

Response

200 (OK)
Content-Type: application/json
{"styleSettings" :
   {"chartPalette": [ 
      { "guid": "guid1", "fill": { "r":255, "g":255, "b":0 } }, 
      { "guid": "guid2", "fill": { "r":255, "g":255, "b":40 } }, 
      { "guid": "guid3", "fill": { "r":255, "g":255, "b":80 } }, 
      { "guid": "guid4", "fill": { "r":255, "g":255, "b":120 } }, 
      { "guid": "guid5", "fill": { "r":255, "g":255, "b":180 } }, 
      { "guid": "guid6", "fill": { "r":255, "g":255, "b":200 } } 
      ]
   }
}

DELETE

/gdc/projects/{project-id}/styleSettings

To Delete/Reset your own custom colour palette in given Project

Response

204 (No Content)

GET

/gdc/projects/{project-id}/roles

To GET User roles for given project. Use following API call. There are 6 default roles (id 1-5), but these IDs are not fixed for specific user roles. You have to GET role details (following API call below) to set User roles correctly.

Response

200 (OK)
Content-Type: application/json
{
    "projectRoles": {
        "roles": [
            "/gdc/projects/{project-id}/roles/{role-id}",
            "/gdc/projects/{project-id}/roles/{role-id}"
        ],
        "links": {
            "project": "/gdc/projects/{project-id}/"
        }
    }
}

GET

/gdc/projects/{project-id}/roles/{role-id}

To GET details about specific project role, use this API call.

Response

200 (OK)
{
    "projectRole": {
        "permissions": {
            "canAccessIntegration": "0",
            "canCreateProjectDashboard": "0",
            "canManageComment": "0",
            "canCreateDimensionMapping": "0",
            "canInitData": "0",
            "canManageIntegration": "0",
            "canManageFolder": "0",
            "canInviteUserToProject": "0",
            "canCreateDomain": "0",
            "canCreateTableDataLoad": "0",
            "canSeeOtherUserDetails": "0",
            "canCreateETLInterface": "0",
            "canCreateRole": "0",
            "canCreateReportResult": "1",
            "canCreateHelp": "0",
            "canManageDomain": "0",
            "canManageAttributeLabel": "0",
            "canCreateColumn": "0",
            "canManageReport": "0",
            "canManageDataSet": "0",
            "canSetUserVariables": "0",
            "canCreateAttributeGroup": "0",
            "canValidateProject": "0",
            "canMaintainProject": "0",
            "canCreateETLFile": "0",
            "canCreateScheduledMail": "0",
            "canManageETLSession": "0",
            "canSuspendUserFromProject": "0",
            "canMaintainUserFilterRelation": "0",
            "canManageAttribute": "0",
            "canManageReportDefinition": "0",
            "canCreateReportResult2": "1",
            "canMaintainUserFilter": "0",
            "canCreateReport": "0",
            "canManageETLFile": "0",
            "canCreateComment": "0",
            "canCreateDataSet": "0",
            "canCreateTable": "0",
            "canManageTableDataLoad": "0",
            "canManageDimensionMapping": "0",
            "canCreateMetric": "0",
            "canRefreshData": "0",
            "canManageProjectDashboard": "0",
            "canManageProject": "0",
            "canManagePrompt": "0",
            "canManageETLInterface": "0",
            "canManageReportResult2": "0",
            "canAccessWorkbench": "0",
            "canCreateAttributeLabel": "0",
            "canManageColumn": "0",
            "canCreatePrompt": "0",
            "canManagePublicAccessCode": "0",
            "canListUsersInProject": "0",
            "canManageAttributeGroup": "0",
            "canManageMetric": "0",
            "canManageHelp": "0",
            "canManageTable": "0",
            "canSetProjectVariables": "0",
            "canCreateETLSession": "0",
            "canCreateFolder": "0",
            "canManageFact": "0",
            "canListInvitationsInProject": "0",
            "canManageScheduledMail": "0",
            "canManageReportResult": "1",
            "canManageAnnotation": "0",
            "canSeePublicAccessCode": "0",
            "canCreateReportDefinition": "1",
            "canCreateFact": "0",
            "canCreateAttribute": "0",
            "canAssignUserWithRole": "0",
            "canCreateAnnotation": "0"
        },
        "links": {
            "roleUsers": "/gdc/projects/{project-id}/roles/{role-id}/users"
        },
        "meta": {
            "created": "2012-07-25 11:28:52",
            "identifier": "dashboardOnlyRole",
            "summary": "dashboard only",
            "author": "/gdc/account/profile/{user-id}",
            "updated": "2012-07-25 11:28:52",
            "title": "Embedded Dashboard Only",
            "contributor": "/gdc/account/profile/{user-id}"
        }
    }
}

POST

/gdc/md/{project-id}/service/timezone

Response

200 (OK)
Content-Type: application/json
{
 "service": {
    "timezone": "UTC"
            }
}

User

To manage users via the User Provisioning API Resources, you need to have your own domain. If you have it, you can simply use the requests below.

User Properties

  • login (string) : User login

  • password (string) : User password

  • verifyPassword (string) : Password for verification

  • email : User's email for invitations, used as contact email

  • firstname (string) : User's firstname

  • lastname (string) : User's lastname

  • userRoles (uri) : Uri to the specific user roles

  • projectUsersUpdateResult : Give an array of successful/failed created users

  • companyName (string) : Name of user's company

  • country (string) : User's country

  • created (date) : Date of user creation

  • updated (date) : Date of user properties update

  • phoneNumber : User's phonenumber

  • position (string) : User's position in a company

  • authenticationModes (array of strings) : an optional field specifying authentication modes (SSO, PASSWORD) allowed for this user. The value of this field overrides the global settings for the domain.

POST

/gdc/account/domains/{organization-name}/users

To create new user in your domain - use this resource. The API will give you new user's uri. You have to be ORGANIZATION admin for provision the user to the Project.

Response

200 (OK)
{
"uri" : "/gdc/account/profile/{profile-id}"
}

GET

/gdc/account/domains/{organization-name}/users

Lists all users in a domain

Response

200 (OK)
{
    "accountSettings": {
        "paging": {
            "offset": 0,
            "count": 14
        },
        "items": [
            {
                "accountSetting": {
                    "companyName": "Company",
                    "country": "cz",
                    "created": "2011-08-10 08:37:46",
                    "firstName": "John",
                    "lastName": "Doe",
                    "login": "user.name@company.com",
                    "ssoProvider":"SSO-PROVIDER",
                    "phoneNumber": "+420724722926",
                    "position": "",
                    "settings": "{\"_VERSION\":\"1.1\",\"currentProjectUri\":\"/gdc/projects/{project-id}\",\"/gdc/projects/{project-id}\":{\"dashboard\":[\"/gdc/md/{project-id}/obj/{obj-id}\",\"abcdef\"]},\"releaseNotice\":[\"stable_67\"],\"/gdc/projects/{project-id}\":{\"dashboard\":[\"/gdc/md/{project-id}/obj/{obj-id}\",\"ghchijk\"]},\"hint-projectPage-invite-people\":false,\"/gdc/projects/{project-id}\":{\"dashboard\":[\"/gdc/md/{project-id}/obj/{obj-id}\",\"lmnopq\"]}}",
                    "timezone": null,
                    "updated": "2012-02-20 16:20:28",
                    "links": {
                        "projects": "/gdc/account/profile/{user-id}/projects",
                        "self": "/gdc/account/profile/{user-id}"
                    }
                }
            },
            {
                "accountSetting": {
                    "companyName": "",
                    "country": "",
                    "created": "2011-11-03 15:16:52",
                    "firstName": "Alice",
                    "lastName": "Wonderland",
                    "login": "example@company.com",
                    "phoneNumber": "",
                    "position": "",
                    "settings": "",
                    "timezone": null,
                    "ssoProvider":"SSO-PROVIDER",
                    "updated": "2011-12-15 14:40:37",
                    "links": {
                        "projects": "/gdc/account/profile/{user-id}/projects",
                        "self": "/gdc/account/profile/{user-id}"
                    }
                }
            }
        ]
    }
}

GET

/gdc/account/domains/{organization-name}/users?login={some-encoded-login}

To GET specific user in Organization that fits the login parameter.

Login parameter: You can use login parameter that will return exactly one user object specify by email that is encoded. Example
login: user@gooddata.com will be encoded as ?login=user%40gooddata.com

Response

200 (OK)
 {
      "accountSettings": {
          "paging": {
              "offset": 0,
              "count": 1
        },
        "items": [
            {
                "accountSetting": {
                    "companyName": null,
                    "country": null,
                    "created": "2014-02-24 18:51:53",
                    "firstName": "John",
                    "lastName": "Doe",
                    "login": "example@company.com",
                    "phoneNumber": null,
                    "position": null,
                    "timezone": null,
                    "updated": "2014-02-24 18:51:53",
                    "links": {
                        "projects": "/gdc/account/profile/{user-id}/projects",
                        "self": "/gdc/account/profile/{user-id}"
                    },
                    "email": "example@company.com"
                }
            }
        ]
    }
 }

GET

/gdc/projects/{project-id}/users?offset=0&limit=5

To GET all users in Project

Paging: This resource optionally allows paging. Use offset and limit parameters on the end of the URI. example: users?offset=1&limit=3

Response

200 (OK)
{
   "users" : [
      {
         "user" : {
            "content" : {
               "email" : "user@domain.com",
               "firstname" : "John",
               "userRoles" : [
                  "/gdc/projects/{project_id}/roles/{role-id}"
               ],
               "phonenumber" : "+777777777",
               "status" : "ENABLED",
               "lastname" : "Doe",
               "login" : "user@domain.com"
            },
            "links" : {
               "roles" : "/gdc/projects/{project_id}/users/{user-id}/roles",
               "permissions" : "/gdc/projects/{project_id}/users/{user-id}/permissions",
               "groups" : "/gdc/projects/{project_id}/users/{user-id}/groups",
               "self" : "/gdc/account/profile/{project_id}",
               "invitations" : "/gdc/account/profile/{project_id}/invitations",
               "projects" : "/gdc/account/profile/{project_id}/projects",
               "projectRelUri" : "/gdc/projects/{project_id}/users/{user-id}"
            },
            "meta" : {
               "created" : "2011-08-10 08:37:46",
               "updated" : "2013-05-27 11:08:09",
               "author" : "/gdc/account/profile/{user-id}",
               "title" : "Jane Doe",
               "contributor" : "/gdc/account/profile/{user-id}"
            }
         }
      }
   ]
}

POST

/gdc/projects/{project-id}/users

To add created User to the Project. There are several default User roles in every project:

  • readOnlyUserRole

  • dashboardOnlyRole

  • adminRole

  • editorRole

  • unverifiedAdminRole

These roles don't have fixed ID. You need to GET the information from diferent API call. See the Project API section.

Response

200 (OK)
{"projectUsersUpdateResult":{
    "successful":["/gdc/account/profile/{user-id}"],
    "failed":[]}
}

POST

/gdc/projects/{project-id}/users

To disable user in the Project use similar call as for provisioning. But use the DISABLED key word instead

Response

200 (OK)
{"projectUsersUpdateResult":{
    "successful":["/gdc/account/profile/{user-id}"],
    "failed":[]}
}

GET

/gdc/account/profile/current

You can get information about your currently logged in user.

Response

200 (OK)

POST

/gdc/projects/{project-id}/invitations

Use this resource for invite user to the Project. The invitation email will be sent.

Response

200 (OK)
{
    "createdInvitations": {
        "uri": [
            "/gdc/projects/{project-id}/invitations/{invitation-id}"
        ]
    }
}

PUT

/gdc/account/profile/{user-id}

You are able to update the User information

Response

200 (OK)

DELETE

/gdc/account/profile/{user-id}

Use this request to delete User

Response

200 (OK)

Project Model

The data model is the core concept of GoodData. It can be managed and validated using following API resources. Model is created/managed by using the MAQL language and script.

Model properties

  • maql : MAQL script for creating/updating logical data model

  • validateProject : IO - Input/Output, LDM - Logical Data Model, PDM - Physical Data Model

Limitations

Most severe limitation of current Project Model API is it's inability to work with projects in which single dataset contains a hierarchy of attributes (other than relation between dataset's anchor and it's other attributes). For the API to work correctly, all datasets in project's logical data model must be loading a single star schema. This is always true for models maintained via cl-tool, CloudConnect or Project Model API, however, this requirement may be easily broken when modyfying project's model directly through MAQL DDL. We'll try to improve the expressiveness of the API (and with this, expanding the set of supported projects) in the future.

Project Model Representation

Common properties of model objects:

Types of object for which the given property is applicable are included in parentheses.

  • identifier required (dataset, attribute, fact, label) - identifier unique among all objects; it must start with a letter, followed by lower and upper-case letters, numbers, dots . and underscores _

  • title required (dataset, date dimension, attribute, fact, label) - short human-readable description of the object; main representation of the object in UI

  • description (dataset, attribute, fact, label) - longer human-readable description of the object

  • folder (attribute, fact) - title of folder in which the object should be categorized

  • dataType (fact, label) - specifies data type of values loaded for the given object; defaults to DECIMAL(12,2) for facts and VARCHAR(128) for labels

Special properties of model objects:

  • Dataset

    • anchor - attribute with finest granularity (same granularity as facts, if there are any) that provides identity to dataset records and can be used for COUNTing number of records in it's fact table; dataset A is required to have an anchor with at least one label if there's a dataset B that has a reference to A (values of anchor's label are used to link data from multiple datasets together)
    • attributes - all other attributes in the dataset (except anchor); these have coarser granularity than the anchor and can be used in reports build from facts in the same dataset; f.ex. if anchor is Employee ID then Sex could be one of the attributes
    • facts - facts about the concept identified by anchor; f.ex. if anchor is Employee ID, Age could be one of the facts
    • references - array of identifiers of other datasets and names of date dimensions; if dataset Employee has a reference to dataset Department, then you can use attributes of Department in reports based on facts of Employee
  • DateDimension

    • name required - identifies the date dimension; rules for identifiers apply (must be unique, limited characters)
  • Attribute

    • defaultLabel - identifier of the label that contains default visual representation of attribute's value
    • sortOrder - defines how attribute values should be ordered; you must specify label to sort by and direction - sample value: { "attributeSortOrder" : { "label" : "label.person.id.name", "direction" : "ASC" } }
  • Label

    • type - type of label; defaults to GDC.text; supported values:
      • GDC.text - normal label, presented as plain text in the UI
      • GDC.link - label contains URL and is presented as clickable hyperlink in the UI

Obtaining current LDM of a project

Assembly of project model is currently a lehgthy process and so the API has to be asynchronous. We'll try to optimize this in the future.

When inspecting project metadata, we may find out that project does not conform to rules described in Limitations. The result in that case will still be a 200 OK, but you'll see some validation errors returned together with the resulting model. You should not rely on such model. It's only provided for convenience so that it can be inspected. You won't be able to modify such project through Project Model API.

Properties of validation error:

  • code - unique code of the type of validation problem (can be relied on as a localization key for message)

  • context - array of identifiers of objects breaking validation rules

  • message - human-readable message describing the problem (with %s placeholders for message params)

  • parameters - parameters for the message

  • reparable - true if this problem can be repaired through this API, false if you won't be available to perform diffs against such project & will have to resolve the problem manually (f.ex. through hand-crafted MAQL DDL)

List of validation errors will be empty for projects with supported models. If it isn't, you'll have to manually resolve (through MAQL DDL) all issues before you'll be able to use this API to update such project's model.

GET

/gdc/projects/{project-id}/model/view

Starts project model assembly. Returns link to a polling resource that will eventually return assembled model.

Response

202 (Accepted)
Content-Type: application/json
Location: /gdc/projects/{project-id}/model/view/{view-id}
{
    "asyncTask": {
        "link": {
            "poll": "/gdc/projects/{project-id}/model/view/{view-id}"
        }
    }
}

GET

/gdc/projects/{project-id}/model/view/{view-id}

Poll to obtain assembled project model.

Generate MAQL DDL to update project

Resources to generate MAQL DDL to update project's model to the desired target state. It does not modify the model itself, but gives you MAQL DDL scripts that can be executed via the /gdc/md/{project-id}/ldm/manage2 resource.

The result

Update operations

Diff between the two model states - operations that should be applied to current project model to make it equal to the submitted targetModel. The list is not meant to be an authoritative representation of the diff. It's granularity is based on current MAQL DDL grammar and it can be changed in the future without notice. It's therefore more useful for presentation to user for inspection than automatic inspection in code.

List of update operations will be empty if the project's model is already equal to the provided targetState.

Each update operation has the following properties:

  • type - unique identifier of operation type (can be relied on as localization key for the description); in time, new operation types may be created and old ones discontinued; we don't recommend relying on it's value for anything besides grouping simmilar changes together

  • dataset - optional identifier of the dataset to which this operation is related; inteded for presentation purposes

  • destructive - true if the operation may result in dropping existing PDM objects, false otherwise

  • description - human-readable description of the change (with %s placeholders for parameters)

  • parameters - parameters for the description

Update scripts

If the list of update operations is non-empty, updateScripts property of the response will contain one or more variants of MAQL DDL that can be executed to actually evolve project's model. Each variant is generated with distinct settings and some combination of optionas may not be available (see below).

Each update script has the following properties:

  • maqlDdlChunks - a list of MAQL DDL scripts that can executed sequentially via the /gdc/md/{project-id}/ldm/manage2 resource to actually perform model evolution

  • preserveData - true if script execution won't truncate data currently loaded in affected datasets, false otherwise; some changes of the model will result in this option not being available (preserveData: false in all update script variants)

  • cascadeDrops - true if generated MAQL use DROPs with the CASCADE option; such drops transitively delete all dashboard objects connected to the dropped LDM object, so you should only execute it if you're certain that you don't need metrics / reports / dashboards that use the dropped object; if the generated MAQL doesn't drop anything, this option will be false in all update script variants

Example

In the example below, we simulate generation of evolution MAQL script for the model included in the example response of the /gdc/projects/{project-id}/model/view resource. The target model contains one extra fact (fact.employee.age).

POST

/gdc/projects/{project-id}/model/diff

Post desired target LDM state to start the MAQL generation process. Returns link to a polling resource that will eventually return the diff.

Response

202 (Accepted)
Content-Type: application/json
Location: /gdc/projects/{project-id}/model/diff/{diff-id}
{
    "asyncTask": {
        "link": {
            "poll": "/gdc/projects/{project-id}/model/diff/{diff-id}"
        }
    }
}

GET

/gdc/projects/{project-id}/model/diff/{diff-id}

Poll to get resulting diff & MAQL.

Response

202 (Accepted)
Content-Type: application/json
{
    "asyncTask": {
        "link": {
            "poll": "/gdc/projects/{project-id}/model/diff/{diff-id}"
        }
    }
}

Response

200 (OK)
Content-Type: application/json
{
    "projectModelDiff" : {
        "updateOperations": [
            {
                "updateOperation": {
                    "type": "create.fact",
                    "dataset": "dataset.employee",
                    "destructive": false,
                    "description": "Create Fact '%s'",
                    "paramaters": ["Employee Age"]
                }
            }
        ],
        "updateScripts": [
            {
                "updateScript": {
                    "maqlDdlChunks": [ "CREATE FOLDER {ffld.employee} VISUAL(TITLE \"Employee\") TYPE FACT;\nCREATE FACT {fact.employee.age} VISUAL(TITLE \"Employee Age\", FOLDER {ffld.employee}) AS {f_employee.f_age};\nALTER DATASET {dataset.employee} ADD {fact.employee.age};\nSYNCHRONIZE {dataset.employee} PRESERVE DATA;" ],
                    "preserveData": true,
                    "cascadeDrops": false
                }
            },
            {
                "updateScript": {
                    "maqlDdlChunks": [ "CREATE FOLDER {ffld.employee} VISUAL(TITLE \"Employee\") TYPE FACT;\nCREATE FACT {fact.employee.age} VISUAL(TITLE \"Employee Age\", FOLDER {ffld.employee}) AS {f_employee.f_age};\nALTER DATASET {dataset.employee} ADD {fact.employee.age};\nSYNCHRONIZE {dataset.employee};" ],
                    "preserveData": false,
                    "cascadeDrops": false
                }
            }
        ]
    }
}

Execute MAQL DDL and Project Model Validation

Resources to execute MAQL DDL to create/update project's model to the desired target state.

POST

/gdc/md/{project-id}/ldm/manage

WARNING! - This resource will be deprecated. Please use ldm/manage2 instead.

Response

200 (OK)

POST

/gdc/md/{project-id}/ldm/manage2

Resource for executing MAQL DDL Scripts for data model management. The resource is asynchronous, you have to poll the returned URL to get the result. Follow the instructions in the article to learn more details about Data Model Creation.

Response

200 (OK)
Content-Type: application/json
{
"entries" : [
     {
         "link" : "/gdc/md/{project-id}/tasks/{task-id}/status",
         "category" : "tasks-status"
     }
            ]
}

GET

/gdc/md/{project-id}/tasks/{task-id}/status

Resource for retrieving the asynchronous task status.

Response

200 (OK)
Content-Type: application/json
{
 "wTaskStatus" : {
    "poll" : "/gdc/md/{project-id}/tasks/{task-id}/status",
    "status" : "OK"
        }
}

POST

/gdc/md/{project-id}/validate/

Use this method to validate Project

Response

201 (Created)
{"uri" : "/gdc/md/{project-id}/validate/{task-id}"}

GET

/gdc/md/{project-id}/ldm/singleloadinterface/{dataset-name}/manifest

Here you can GET the SLI manifest. This manifest is needed to upload your data using the API directly. The SLI manifest provides column mapping between CSV file and data model.

Response

200 (OK)
{
    "dataSetSLIManifest": {
        "parts": [
            {
                "columnName": "f_quotes.dt_quote_date_id",
                "populates": [
                    "quote.date.mdyy"
                ],
                "constraints": {
                    "date": "yyyy-MM-dd"
                },
                "mode": "FULL",
                "referenceKey": 1
            },
            {
                "columnName": "d_quotes_sector.nm_sector",
                "populates": [
                    "label.quotes.sector"
                ],
                "mode": "FULL",
                "referenceKey": 1
            },
            {
                "columnName": "d_quotes_market.nm_market",
                "populates": [
                    "label.quotes.market"
                ],
                "mode": "FULL",
                "referenceKey": 1
            },
            {
                "columnName": "f_quotes.f_low_price",
                "populates": [
                    "fact.quotes.low_price"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "f_quotes.nm_id",
                "populates": [
                    "label.quotes.id"
                ],
                "mode": "FULL",
                "referenceKey": 1
            },
            {
                "columnName": "f_quotes.f_volume",
                "populates": [
                    "fact.quotes.volume"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "f_quotes.dt_quote_date",
                "populates": [
                    "dt.quotes.quote_date"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "f_quotes.f_open_price",
                "populates": [
                    "fact.quotes.open_price"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "d_quotes_symbol.nm_symbol",
                "populates": [
                    "label.quotes.symbol"
                ],
                "mode": "FULL",
                "referenceKey": 1
            },
            {
                "columnName": "d_quotes_symbol.nm_company",
                "populates": [
                    "label.quotes.symbol.company"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "f_quotes.f_high_price",
                "populates": [
                    "fact.quotes.high_price"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "d_quotes_industry.nm_industry",
                "populates": [
                    "label.quotes.industry"
                ],
                "mode": "FULL",
                "referenceKey": 1
            },
            {
                "columnName": "f_quotes.f_close_price",
                "populates": [
                    "fact.quotes.close_price"
                ],
                "mode": "FULL"
            },
            {
                "columnName": "f_quotes.f_adjusted_close_price",
                "populates": [
                    "fact.quotes.adjusted_close_price"
                ],
                "mode": "FULL"
            }
        ],
        "file": "dataset.quotes.csv",
        "dataSet": "dataset.quotes"
    }
}

Data Upload

The Data Upload API can be used for uploading the data directly to your Project. Using the resources below, you are able to start data uplaod process with the file package stored on GoodData WebDav Server (secure-di.gooddata.com/uploads/). The package must contain upload_info.json and CSV file for every dataset that you want to upload.

Upload properties

  • pullIntegration : path to directory where your upload package is stored

  • pullTask : asynchronous task that is created for each data upload process

POST

/gdc/md/{project-id}/etl/pull

Start data upload using this resource. As parameter, use the name of WebDav directory, where you uploaded Data. Upload archive should be named upload.zip and must contain upload_info.json (SLI manifest) and CSV file with data. See the Data Model resources to learn about SLI manifest.

Response

200 (OK)
{
   "pullTask" : {
      "uri" : "/gdc/md/{project-id}/etl/task/{task-id}"
   }    
}

GET

/gdc/md/{project-id}/etl/task/{task-id}

This is resource returned by previous POST. Poll it to get the upload status.

Response

200 (OK)
{
   "taskStatus" : "OK | ERROR | WARNING" 
}

GET

/gdc/md/{project-id}/data/uploads/{dataset-object-id}

This resource gives you status of data uploads for specific dataset. You need to specify dataset ID in the end of the URI. This ID can be find in gdc/md/{project-id}/query/datasets resource. See the next resource definition below.

Response

200 (OK)
{
   "dataUploads" : {
      "uploads" : [
         {
            "dataUpload" : {
               "warnings" : [],
               "msg" : null,
               "etlInterface" : "/gdc/md/{project-id}/obj/{obj-id}",
               "progress" : "1.000",
               "status" : "OK",
               "file" : "upload_info.json",
               "fullUpload" : 1,
               "uri" : "/gdc/md/{project-id}/data/upload/{upload-id}",
               "createdAt" : "2012-12-14 13:40:36",
               "fileSize" : 155649,
               "processedAt" : "2012-12-14 13:40:38"
            }
         },
         {
            "dataUpload" : {
               "warnings" : [],
               "msg" : null,
               "etlInterface" : "/gdc/md/{project-id}/obj/{obj-id}",
               "progress" : "1.000",
               "status" : "OK",
               "file" : "upload_info.json",
               "fullUpload" : 1,
               "uri" : "/gdc/md/{project-id}/data/upload/{upload-id}",
               "createdAt" : "2012-12-14 13:33:39",
               "fileSize" : 78957,
               "processedAt" : "2012-12-14 13:33:40"
            }
         },
         {
            "dataUpload" : {
               "warnings" : [],
               "msg" : null,
               "etlInterface" : "/gdc/md/{project-id}/obj/{obj-id}",
               "progress" : "1.000",
               "status" : "OK",
               "file" : "upload_info.json",
               "fullUpload" : 1,
               "uri" : "/gdc/md/{project-id}/data/upload/{upload-id}",
               "createdAt" : "2012-12-14 09:24:42",
               "fileSize" : 144,
               "processedAt" : "2012-12-14 09:24:59"
            }
         },
         {
            "dataUpload" : {
               "warnings" : [],
               "msg" : null,
               "etlInterface" : "/gdc/md/{project-id}/obj/{obj-id}",
               "progress" : "1.000",
               "status" : "OK",
               "file" : "upload_info.json",
               "fullUpload" : 1,
               "uri" : "/gdc/md/{project-id}/data/upload/{upload-id}",
               "createdAt" : "2012-12-13 17:06:11",
               "fileSize" : 144,
               "processedAt" : "2012-12-13 17:06:17"
            }
         }
      ],
      "links" : {}
   }
}

GET

/gdc/md/{project-id}/query/datasets

This resource helps you identify datasets in your project. You can easily identify dataset object id in the response.

Response

200 (OK)
{
    "query": {
        "entries": [
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2009-07-03 14:52:50",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Initially Assigned Date",
                "updated": "2009-07-03 14:52:50",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2010-06-16 01:11:00",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Zendesk Tickets",
                "updated": "2011-02-18 19:38:40",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2010-06-16 01:11:04",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Zendesk Tags",
                "updated": "2011-02-10 16:07:11",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2009-07-03 14:52:50",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Last Updated Date",
                "updated": "2009-07-03 14:52:50",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2009-07-03 14:52:50",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Assigned Date",
                "updated": "2009-07-03 14:52:50",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2009-07-03 14:52:50",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Solved Date",
                "updated": "2009-07-03 14:52:50",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2009-07-03 14:52:50",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Due Date",
                "updated": "2009-07-03 14:52:50",
                "contributor": "/gdc/account/profile/{user-id}"
            },
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2009-07-03 14:52:50",
                "deprecated": "0",
                "summary": "",
                "category": "dataSet",
                "title": "Created Date",
                "updated": "2009-07-03 14:52:50",
                "contributor": "/gdc/account/profile/{user-id}"
            }
        ],
        "meta": {
            "summary": "Metadata Query Resources for project '{project-id}'",
            "title": "List of datasets",
            "category": "query"
        }
    }
}

Notifications

Notifications allow users to be informed about some specific events in the Project. Notifications are based on Channel Configuration, where user specifies what is the channel, where he wants to send the notification. Second step is a Subscription settings, that will subscribe the user to a specific channel with specific condition for triggering the notification.

Notifications properties

  • channelConfiguration : Specifies the channel configuration configuration

  • username (string) : User's channel login for specific channel

  • password (string) : User's password for specific configuration

  • title (string) : Title of channel configuration

  • author (uri) : URI of user who creates the notification channel

  • created (date) : Date of channel configuration creation

  • updated (date) : Date of channel configuration update

  • from : Phone number of notification sender (for Twillio Channel)

  • to : Phone number of notification recipient (for Twillio Channel)

  • timerEvent (cron Expression) : Specifies the interval for notification check

  • condition : Condition that must be fulfil to send the notification

  • message : Message that is sent via specific channel as notification

POST

/gdc/account/profile/{profile-id}/channelConfigurations

To create new Salesforce Notifications channel use this method

Response

201 (Created)
{
    "channelConfiguration": {
        "configuration": {
            "sfdcChatterConfiguration": {
                "username": "USERNAME@DOMAIN.COM"
            }
        },
        "meta": {
            "title": "Channel Name",
            "author": "/gdc/account/profile/{user-id}",
            "category": "channelConfiguration",
            "updated": "2011-12-20 13:43:17",
            "created": "2011-12-20 13:43:17",
            "uri": "/gdc/account/profile/{user-id}/channelConfigurations/{channel-id}"
        }
    }
}

POST

/gdc/projects/{project-id}/users/{user-id}/subscriptions

To create new Subscription, call this resource and set the timerEvent, condition expression and message that will be sent

Response

201 (Created)
{
    "subscription": {
        "triggers": [
            {
                "timerEvent": {
                    "cronExpression": "0 0/5 * * * *"
                }
            }
        ],
        "condition": {
            "condition": {
                "expression": "f:executeMetric('/gdc/md/{project-id}/obj/{obj-id}') < 0.99"
            }
        },
        "message": {
            "template": {
                "expression": "Custom message % ${f:executeMetric('/gdc/md/{project-id}/obj/{obj-id}')} ..."
            }
        },
        "channels": [
            "/gdc/account/profile/{user-id}/channelConfigurations/{channel-id}"
        ],
        "meta": {
            "title": "TEST%",
            "author": "/gdc/account/profile/{user-id}",
            "category": "subscription",
            "updated": "2011-12-20 13:59:23",
            "created": "2011-12-20 13:59:23",
            "uri": "/gdc/projects/{project-id}/users/{user-id}/subscriptions/{subscription-id}"
        }
    }
}

Report

You can manage reports using APIs. Use following resources to get a list of all reports , or execute and export selected reports.

Common Use Cases:

Report Export

  1. Use the GET gdc/md/{project-id}/query/reports

  2. Identify the report you want to export by report metadata.

  3. POST the report to gdc/xtab2/executor3 to compute the latest numbers. Use one of the following options:

    • Report Definition URI
    • Report URI
  4. POST the JSON response to gdc/exporter/executor

  5. Download the Report file

Report Creation

  1. POST the valid Report Definition object to gdc/md/{project-id}/obj

  2. Use returned object URI (report definition) to save it as a Report by POSTing Report JSON to gdc/md/{project-id}/obj

  3. Execute the Report by sending POST to gdc/xtab2/executor3 with one of the following options

    • Report Definition URI
    • Report URI

Report Properties

  • link (uri) : Link to specific Report

  • author (uri) : URI of Report author

  • tags : Report tags

  • created (date) : Report creation date

  • updated (date) : Report update date

  • summary (string) : Report text summary

  • report (uri) : Specific report URI

  • format : Report export format (pdf, csv, png)

GET

/gdc/md/{project-id}/query/reports

Use this method to list all Reports in given Project

Response

200 (OK)
Content-Type: application/json
{
    "query": {
        "entries": [
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2011-11-23 15:34:18",
                "deprecated": "0",
                "summary": "",
                "title": "Report Title",
                "category": "report",
                "updated": "2011-11-23 15:41:44",
                "contributor": "/gdc/account/profile/{user-id}"
            }],
        "meta": {
            "summary": "Metadata Query Resources for project '{project-id}'",
            "title": "List of reports",
            "category": "query"
        }
    }
}

POST

/gdc/md/{project-id}/obj

You need to create Report Definition using this resource first, then save it as a Report by following API call.

Response

201 (Created)
{
   "uri" : "/gdc/md/{project-id}/obj/{created-object-id}"
}

POST

/gdc/md/{project-id}/obj

This resource will allow you to save Report Definition as a Report (visible from UI). You need to POST the Report Definition.

Response

201 (Created)
{
   "uri" : "/gdc/md/{project-id}/obj/{created-report-object-id}"
}

POST

/gdc/xtab2/executor3

Use this method to execute selected Report using the Report Definition URI.

Response

201 (Created)
{
   "execResult" : {
      "reportView" : {
         "chart" : {
            "styles" : {
               "global" : {
                  "linetype" : "smooth",
                  "colorMapping" : [
                     {
                        "guid" : "guid8",
                        "uri" : "/gdc/md/{project-id}/obj/{obj-id}"
                     }
                  ]
               },
               "yui_3_7_1_1_1355414802308_16890" : {
                  "axis" : {
                     "limits" : {
                        "min" : 0,
                        "max" : 75
                     }
                  }
               }
            },
            "buckets" : {
               "y" : [
                  {
                     "id" : "yui_3_7_1_1_1355414802308_16890",
                     "uri" : "metric"
                  }
               ],
               "color" : [],
               "x" : [
                  {
                     "id" : "yui_3_7_1_1_1355414981915_32707",
                     "uri" : "/gdc/md/{project-id}/obj/{obj-id}"
                  }
               ],
               "angle" : []
            },
            "type" : "area"
         },
         "reportName" : "Mean temperature by date",
         "columnWidths" : [],
         "filters" : [],
         "rows" : [],
         "sort" : {
            "columns" : [],
            "rows" : []
         },
         "oneNumber" : {
            "labels" : {}
         },
         "format" : "chart",
         "columns" : [
            {
               "drillDownStepAttributeDF" : "/gdc/md/{project-id}/obj/{obj-id}",
               "sort" : "pk",
               "displayFormId" : "/gdc/md/{project-id}/obj/{obj-id}",
               "attributeTitle" : "Month (Date)",
               "baseElementURI" : "/gdc/md/{project-id}/obj/{obj-id}/elements?id=",
               "title" : "Month (Date)",
               "attributeId" : "/gdc/md/{project-id}/obj/{obj-id}",
               "totals" : [
                  []
               ]
            },
            "metricGroup"
         ],
         "metrics" : [
            {
               "format" : "#,##0.00",
               "title" : "Mean Temperature [Min]",
               "metricId" : "/gdc/md/{project-id}/obj/{obj-id}"
            }
         ]
      },
      "reportDefinition" : "/gdc/md/{project-id}/obj/{obj-id}",
      "dataResult" : "/gdc/md/{project-id}/dataResult/{result-id}"
   }
}

POST

/gdc/xtab2/executor3

Use this method to execute selected Report using the Report URI.

Response

201 (Created)
{
   "execResult" : {
      "reportView" : {
         "chart" : {
            "styles" : {
               "global" : {
                  "linetype" : "smooth",
                  "colorMapping" : [
                     {
                        "guid" : "guid8",
                        "uri" : "/gdc/md/{project-id}/obj/{obj-id}"
                     }
                  ]
               },
               "yui_3_7_1_1_1355414802308_16890" : {
                  "axis" : {
                     "limits" : {
                        "min" : 0,
                        "max" : 75
                     }
                  }
               }
            },
            "buckets" : {
               "y" : [
                  {
                     "id" : "yui_3_7_1_1_1355414802308_16890",
                     "uri" : "metric"
                  }
               ],
               "color" : [],
               "x" : [
                  {
                     "id" : "yui_3_7_1_1_1355414981915_32707",
                     "uri" : "/gdc/md/{project-id}/obj/{obj-id}"
                  }
               ],
               "angle" : []
            },
            "type" : "area"
         },
         "reportName" : "Mean temperature by date",
         "columnWidths" : [],
         "filters" : [],
         "rows" : [],
         "sort" : {
            "columns" : [],
            "rows" : []
         },
         "oneNumber" : {
            "labels" : {}
         },
         "format" : "chart",
         "columns" : [
            {
               "drillDownStepAttributeDF" : "/gdc/md/{project-id}/obj/{obj-id}",
               "sort" : "pk",
               "displayFormId" : "/gdc/md/{project-id}/obj/{obj-id}",
               "attributeTitle" : "Month (Date)",
               "baseElementURI" : "/gdc/md/{project-id}/obj/{obj-id}/elements?id=",
               "title" : "Month (Date)",
               "attributeId" : "/gdc/md/{project-id}/obj/{obj-id}",
               "totals" : [
                  []
               ]
            },
            "metricGroup"
         ],
         "metrics" : [
            {
               "format" : "#,##0.00",
               "title" : "Mean Temperature [Min]",
               "metricId" : "/gdc/md/{project-id}/obj/{obj-id}"
            }
         ]
      },
      "reportDefinition" : "/gdc/md/{project-id}/obj/{obj-id}",
      "dataResult" : "/gdc/md/{project-id}/dataResult/{result-id}"
   }
}

Export a report

POST

/gdc/exporter/executor

  • scaling (optional) - Specifies scaling when you export a tabular report to PDF format. Scaling applies to both landscape and portrait orientations.
    • pageScalePercentage (optional, integer) - Specifies a percentage to scale the exported PDF. Cannot be used with other scaling keywords. Default: 100
    • scaleToPages (optional, integer) - Specifies a maximum number of pages for the exported PDF. Cannot be used with other scaling keywords.
    • scaleToPagesX (optional, integer) - Shrinks the horizontal content of the exported PDF to a maximum of this number of pages. Often used with the scaleToPagesY keyword. Cannot be combined with the pageScalePercentage or scaleToPages keywords.
    • scaleToPagesY (optional, integer) - Shrinks the vertical content of the exported PDFs to a maximum number of pages. Often used with the scaleToPagesX keyword. Cannot be combined with the pageScalePercentage or scaleToPages keywords.

The content of the result section is execResult JSON (which is returned after report computation).

Response

201 (Created)
{
"uri":"/gdc/exporter/result/{project_id}/{result_id}"
}

Export a large report

Export a large report

POST

/gdc/app/projects/{project_id}/execute/raw/

Use this resource to export reports that are too large to be computed on the UI. It executes in raw form.

Parameters
Name Description Details
project_id

ID of the project where you want to execute a report.

string, required

Response

201 (Created)
{
    "uri":"/gdc/projects/{project_id}/execute/raw/{report_id}"
}

Dashboard

Following resources cover Project Dashboard operation. You can list all Dashboards in Project, GET Dashboard content and update it.

Drill into a dashboard reportItem

You can define a drill for a reportItem on a dashboard. See the example in the JSON of Create a dashboard.

  • drills (optional) - Specifies that you can drill into the object.
    • target (required) - Specifies the type of drill. If the target value is export, you must also include the export object.
      Values: pop-up | in-place | new-window | export
    • export (optional) - Configures the export. Include this object only if you specified a target value of export.
      • format (required) - Specifies the format of the export.
        Values: csv | xlsx
    • definition (required) - Defines the drill object relationships. You can also define the drill from the GoodData Portal.

GET

/gdc/md/{project-id}/query/projectdashboards

Use this method to list of all Dashboards in given Project

Response

200 (OK)
{
  "query": {
    "entries": [
      {
        "link": "/gdc/md/{project-id}/obj/{obj-id}",
        "author": "/gdc/account/profile/{user-id}",
        "tags": "",
        "created": "2012-08-15 19:41:07",
        "deprecated": "0",
        "summary": "",
        "category": "projectDashboard",
        "title": "Overview",
        "updated": "2012-09-04 15:56:36",
        "contributor": "/gdc/account/profile/{user-id}"
      }
    ],
    "meta": {
      "summary": "Metadata Query Resources for project '{project-id}'",
      "title": "List of projectdashboards",
      "category": "query"
    }
  }
}

GET

/gdc/md/{project-id}/obj/{obj-id}

Use this method to GET dashboard object content

Response

200 (OK)
{
    "projectDashboard": {
        "content": {
            "filters": [],
            "tabs": [
                {
                    "title": "Dashboard Name",
                    "identifier": "abcdefg",
                    "items": [
                        {
                            "reportItem": {
                                "positionX": 410,
                                "positionY": 0,
                                "sizeX": 530,
                                "sizeY": 310,
                                "style": {
                                    "background": {
                                        "opacity": 0
                                    }
                                },
                                "obj": "/gdc/md/{project-id}/obj/{obj-id}",
                                "visualization": {
                                    "oneNumber": {
                                        "labels": {}
                                    },
                                    "grid": {
                                        "columnWidths": []
                                    }
                                },
                                "filters": []
                            }
                        },
                        {
                            "headlineItem": {
                                "positionX": 0,
                                "positionY": 0,
                                "sizeX": 380,
                                "sizeY": 80,
                                "title": "Sales",
                                "metric": "/gdc/md/{project-id}/obj/{obj-id}",
                                "format": "#,##0.00 Kc \n",
                                "filters": [],
                                "filterAttributeDF": "/gdc/md/{project-id}/obj/{obj-id}",
                                "linkedWithExternalFilter": 0,
                                "constraint": {
                                    "to": 0,
                                    "from": 0,
                                    "type": "floating"
                                },
                                "trendlineConfig": {
                                    "autoGranularity": 0,
                                    "granularityAttributeDF": "/gdc/md/{project-id}/obj/{obj-id}"
                                }
                            }
                        },
                        {
                            "reportItem": {
                                "positionX": 0,
                                "positionY": 350,
                                "sizeX": 940,
                                "sizeY": 360,
                                "style": {
                                    "background": {
                                        "opacity": 0
                                    }
                                },
                                "obj": "/gdc/md/{project-id}/obj/{obj-id}",
                                "visualization": {
                                    "oneNumber": {
                                        "labels": {}
                                    },
                                    "grid": {
                                        "columnWidths": []
                                    }
                                },
                                "filters": []
                            }
                        },
                        {
                            "lineItem": {
                                "positionX": 30,
                                "positionY": 320,
                                "sizeX": 880,
                                "sizeY": 10
                            }
                        },
                        {
                            "lineItem": {
                                "positionX": 390,
                                "positionY": 0,
                                "sizeX": 9,
                                "sizeY": 310
                            }
                        },
                        {
                            "textItem": {
                                "positionX": 100,
                                "positionY": 130,
                                "sizeX": 170,
                                "sizeY": 30,
                                "style": {
                                    "background": {
                                        "opacity": 0
                                    }
                                },
                                "textSize": "middle",
                                "text": "# Customers"
                            }
                        },
                        {
                            "reportItem": {
                                "positionX": 80,
                                "positionY": 160,
                                "sizeX": 210,
                                "sizeY": 140,
                                "style": {
                                    "background": {
                                        "opacity": 0
                                    }
                                },
                                "obj": "/gdc/md/{project-id}/obj/{obj-id}",
                                "visualization": {
                                    "oneNumber": {
                                        "labels": {
                                            "description": ""
                                        }
                                    },
                                    "grid": {
                                        "columnWidths": []
                                    }
                                },
                                "filters": []
                            }
                        }
                    ]
                }
            ]
        },
        "meta": {
            "uri": "/gdc/md/{project-id}/obj/{obj-id}",
            "created": "2012-08-15 19:41:07",
            "updated": "2012-09-03 16:37:57",
            "author": "/gdc/account/profile/{user-id}",
            "contributor": "/gdc/account/profile/{user-id}",
            "summary": "",
            "title": "Overview",
            "category": "projectDashboard",
            "tags": "",
            "deprecated": "0",
            "identifier": "abcdefg"
        }
    }
}

Create a dashboard object

POST

/gdc/md/{project-id}/obj/{obj-id}

Response

200 (OK)
{
  "uri": "/gdc/md/{project_id}/obj/{object_id}"
}

Metadata

project Following resources can be used for exporting/importing selected metadata objects. You will get the import token, that is used for import the metadata to other project.

Metadata Properties

  • partialMDExport (uri) : Specifies metadata objects for export

  • status (uri) : Export result URI

  • token (string) : Export token for Import usage

  • overwriteNewer (boolean) : 1|0 overwrite existing objects

  • updateLDMObjects (boolean) : 1|0 update logical data model objects

Export part of a project

Export partial metadata

POST

/gdc/md/{project_id}/maintenance/partialmdexport

Response

  • status (uri) - URI where you can poll for the status of the export.

  • token (string) - Token to use to import the exported metadata.

Parameters
Name Description Details
project_id

The ID of the project whose metadata you want to export.

string, required

Response

200 (OK)
{
    "partialMDArtifact": {
        "status": {
            "uri": "/gdc/md/{project_id}/tasks/{task_id}/status"
        },
        "token": "TOKEN_STRING"
    }
}

Import part of a project

Import partial metadata

POST

/gdc/md/{project_id}/maintenance/partialmdimport

  • token (string, required) - The project token you want to import. This token is created during export of partial metadata.

  • overwriteNewer (optional, boolean) - Specifies whether imported objects should overwrite newer versions of those objects.
    Default: 0

  • updateLDMObjects (optional, boolean) - Specifies whether to update logical data model objects.
    Default: 0

  • turnOffSchedules (optional, boolean) - Specifies whether imported scheduled emails are active. If value is 0, sending of scheduled emails continues uninterrupted. If value is 1, schedules are imported but no emails are sent until you schedule an email. When you schedule any email, all email schedules become active.
    Default: 0

Parameters
Name Description Details
project_id

The ID of the project where you want to import metadata.

string, required

Response

200 (OK)
{
"uri" : "/gdc/md/{project_id}/etltask/{task_id}"
}

POST

/gdc/internal/projects/{project-id}/objects/setPermissions

This request allow you to set the object specific permissions. You need to list all objects that you want to set the permissions to, specify following options:

  • "lock": true|false - specify whether the object is locked (can be edited only by Project Admin)

  • "listed": true|false - specify the object visibility on UI

If you lock Dashboard, the lock will be applied also for all Reports and Metrics that are part of this dashboard.

Response

200 (OK)
    {
        "permissions": {
            "items": [
                "/gdc/md/{project-id}/obj/{object-id}",
                "/gdc/md/{project-id}/obj/{object-id}"
            ]
        }
    }

Data Permissions

You can use data permission (formerly Mandatory User Filters or MUFs) to filter specific data for specific user. A data permission is based on attribute value identifiers. Data permissions can be assigned to multiple users.

Data Permission Properties

  • userFilter : Specifies the data permission object

  • expression : Defines data permission

  • category : Object category

  • title : data permission title

  • user (uri) : URI of user where the was defined

  • userFiltersUpdateResult : Successful/Failed permissions

  • created (date) : object creation date

  • updated (date) : date of last update

POST

/gdc/md/{project-id}/obj

Use this method to create a new data permission object.

Response

200 (OK)

POST

/gdc/md/{project-id}/userfilters

Use this method to assign a data permission to a user.

Response

200 (OK)
{
  "userFiltersUpdateResult": {
      "failed": [],
      "successful": [
           "/gdc/account/profile/{user-id}"
        ]
    }
}

GET

/gdc/md/{project-id}/query/userfilters

Use this method to get a list of data permission objects for a project.

Response

200 (OK)
{
    "query": {
        "entries": [
            {
                "link": "/gdc/md/{project-id}/obj/{data-permission-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2012-01-16 11:08:13",
                "deprecated": "0",
                "summary": "",
                "title": "User Filter Name",
                "category": "userFilter",
                "updated": "2012-01-16 11:08:13",
                "contributor": "/gdc/account/profile/{user-id}"
            }
        ],
        "meta": {
            "summary": "Metadata Query Resources for project '{project-id}'",
            "title": "List of userfilters",
            "category": "query"
        }
    }
}

GET

/gdc/md/{project-id}/userfilters?users={user-URI}

To list data permissions for selected users, use this API call. You can use multiple user URIs as a parameter. So that you can filter using ...userFilters={user-uri}&{user-uri}&...

Response

200 (OK)
{
    "userFilters": {
        "count": 20,
        "length": 1,
        "offset": 0,
        "items": [
            {
                "userFilters": [
                    "/gdc/md/{project-id}/obj/{obj-id}"
                ],
                "user": "/gdc/account/profile/{user-id}"
            }
        ]
    }
}

GET

/gdc/md/{project-id}/userfilters?userFilters={data-permission-URI}

To list Users for a specific data permission, use this API call. You can use multiple data permission URIs as a parameter. For example...userFilters={data-permission-uri}&{data-permission-uri}&...

Response

200 (OK)
{
    "userFilters": {
        "count": 20,
        "length": 1,
        "offset": 0,
        "items": [
            {
                "userFilters": [
                    "/gdc/md/{project-id}/obj/{obj-id}"
                ],
                "user": "/gdc/account/profile/{user-id}"
            }
        ]
    }
}

DELETE

/gdc/md/{project-id}/obj/{data-permission-object-id}

To DELETE a data permission object.

Response

204 (No Content)

Dependency

This API can be used to GET all objects that are used by specific object such as dashboard, report etc. You can specify

  • used by: to get all objects that use given object

  • using: ti get all objects that are being used by given object

For example one report uses metrics and. If you pass the report object id, the API will give you a list of all objects that are being used by this report.

GET

/gdc/md/{project-id}/usedby/{obj-id}

Use this method GET all objects that use your given object (specified in the request URI)

Response

200 (OK)
{
   "using" : {
      "edges" : [
         {
            "to" : 5,
            "from" : 38
         },
         {
            "to" : 49,
            "from" : 5
         },      
],
     "nodes" : [
    {
           "link" : "/gdc/md/{project-id}/obj/{obj-id}",
           "author" : "/gdc/account/profile/{user-id}",
           "created" : "2011-12-22 11:04:45",
           "deprecated" : "0",
           "summary" : "",
           "updated" : "2011-12-22 11:04:46",
           "title" : "Department Salaries - Total",
           "category" : "report",
           "contributor" : "/gdc/account/profile/{user-id}"
         },
{
           "link" : "/gdc/md/{project-id}/obj/{obj-id}",
           "author" : "/gdc/account/profile/{user-id}",
           "created" : "2011-12-22 11:04:45",
           "deprecated" : "0",
           "summary" : "",
           "updated" : "2011-12-22 11:04:46",
           "title" : "Department Salaries - Total",
           "category" : "report",
           "contributor" : "/gdc/account/profile/{user-id}"
         }
]
     }
}

GET

/gdc/md/{project-id}/using/{obj-id}

Use this method GET all objects that are used by specific object

Response

200 (OK)
{
   "using" : {
      "edges" : [
         {
            "to" : 5,
            "from" : 38
         },
         {
            "to" : 49,
            "from" : 5
         },      
],
     "nodes" : [
    {
           "link" : "/gdc/md/{project-id}/obj/{obj-id}",
           "author" : "/gdc/account/profile/{user-id}",
           "created" : "2011-12-22 11:04:45",
           "deprecated" : "0",
           "summary" : "",
           "updated" : "2011-12-22 11:04:46",
           "title" : "Department Salaries - Total",
           "category" : "report",
           "contributor" : "/gdc/account/profile/{user-id}"
         },
{
           "link" : "/gdc/md/{project-id}/obj/{obj-id}",
           "author" : "/gdc/account/profile/{user-id}",
           "created" : "2011-12-22 11:04:45",
           "deprecated" : "0",
           "summary" : "",
           "updated" : "2011-12-22 11:04:46",
           "title" : "Department Salaries - Total",
           "category" : "report",
           "contributor" : "/gdc/account/profile/{user-id}"
         }
]
     }
}

Object Identifiers

The metadata objects are uniquely identified by the URI and Identifier. You can use this API to transform Identifiers to URI or vice versa. Identifiers doesn’t change when you clone project from master to child.

POST

/gdc/md/{project-id}/identifiers

Use this method transform identifier to URI. See the proper payload.

Response

200 (OK)
{
  "identifiers" : [
    {
      "identifier" : "abcdefg",
      "uri" : "/gdc/md/{project-id}/obj/{obj-id}"
    }
  ]
}

Reports and Dashboards by Email

Using this API, you can easily schedule the Email, that will be sent to you with a defined Reports and/or Dashboards as an attachment.

POST

/gdc/md/{project-id}/obj

Create new scheduleMail object with following this request

Response

200 (OK)
{"uri":"/gdc/md/{project-id}/obj/{obj-id}"}

GET

/gdc/md/{project-id}/query/scheduledmails

List all scheduled emails with this request

Response

200 (OK)
{
    "query": {
        "entries": [
            {
                "link": "/gdc/md/{project-id}/obj/{obj-id}",
                "author": "/gdc/account/profile/{user-id}",
                "tags": "",
                "created": "2012-06-05 15:50:25",
                "deprecated": "0",
                "summary": "Daily at 12:00pm PT",
                "category": "scheduledMail",
                "title": "Scheduled report example",
                "updated": "2012-06-05 15:50:25",
                "contributor": "/gdc/account/profile/{user-id}"
            }
        ],
        "meta": {
            "summary": "Metadata Query Resources for project '{project-id}'",
            "title": "List of scheduledmails",
            "category": "query"
        }
    }
}

Get info about a schedule email

GET

/gdc/md/{project-id}/obj/{obj-id}

Get specific scheduled email details

Response

200 (OK)
     {
     "scheduledMail": {
      "content": {
    "body": "Hey, I'm sending you new Reports and Dashboards!",
    "when": {
        "timeZone": "America/Los_Angeles",
        "recurrency": "0:0:0:1*12:0:0",
        "startDate": "2012-06-05"
    },
    "attachments": [
        {
            "reportAttachment": {
                "exportOptions": {
                    "pageOrientation": "landscape"
                },
                "formats": [
                    "pdf",
                    "xls"
                ],
                "uri": "/gdc/md/{project-id}/obj/{report-id}"
            }
        },
        {
            "dashboardAttachment": {
                "uri": "/gdc/md/{project-id}/obj/{dashboard-object-id}",
                "allTabs": 1,
                "tabs": []
            }
        },
        {
            "dashboardAttachment": {
                "uri": "/gdc/md/{project-id}/obj/{dashboard-object-id}",
                "allTabs": 0,
                "tabs": [
                    "aydpARVaburu"
                ]
            }
        }
      ],
      "to": [
        "user.email@gooddata.com"
      ],
      "subject": "Scheduled report"
       },
       "meta": {
          "author": "/gdc/account/profile/{user-id}",
          "uri": "/gdc/md/{project-id}/obj/{obj-id}",
          "tags": "",
            "created": "2012-06-05 15:50:25",
            "identifier": "abcdefg",
         "deprecated": "0",
         "summary": "Daily at 12:00pm PT",
         "title": "Scheduled report example",
            "category": "scheduledMail",
            "updated": "2012-06-05 15:50:25",
         "contributor": "/gdc/account/profile/{user-id}"
          }
      }
    }

Data Loading Processes

Processes

List Processes in a project

GET

/gdc/projects/{project-id}/dataload/processes

Response

200 (OK)
Content-Type: application/json
{
    "processes" : {
        "items" : [ {
            "process" : {
                "name" : "some_transformation",
                "executables" : [ "graph/downloader.grf", "graph/gd_load.grf", "graph/jsons_parser.grf", "graph/run.grf", "graph/transform.grf" ],
                "links" : {
                    "self" : "/gdc/projects/{project-id}/dataload/processes/{process-id}",
                    "executions" : "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions"
                }
            }
        } ]
    }
}

Create new Process

POST

/gdc/projects/{project-id}/dataload/processes

Use this resource to create new data loading process. Before doing this request, you have to archive (.zip) all your CloudConnect Project files (workspace.prm...) and folders (graph, meta, ...) and upload the archive file to the WebDAV server (https://na1-di.gooddata.com/uploads/).

Response

201 (Created)
Content-Type: application/json
{
    "process" : {
        "name" : "Process Name",
        "executables" : [
            "graph/simple.grf",
            "graph/simpleNoParam.grf"
        ],
        "links" : {
            "self" : "/gdc/projects/{project-id}/dataload/processes/{process-id}",
            "executions" : "/gdc/{project-id}/dataload/processes/{process-id}/executions"
        }
    }
}

Create new Process - multipart upload

POST

/gdc/projects/{project-id}/dataload/processes

Use this resource to create new data loading process with one single multipart http request. You have to archive (.zip) whole CloudConnect Project and send both metadata (json) and data as separated parts of the same request.

Response

201 (Created)
Content-Type: application/json
{
    "process" : {
        "name" : "Process Name",
        "executables" : [
            "graph/simple.grf",
            "graph/simpleNoParam.grf"
        ],
        "links" : {
            "self" : "/gdc/projects/{project-id}/dataload/processes/{process-id}",
            "executions" : "/gdc/{project-id}/dataload/processes/{process-id}/executions"
        }
    }
}

User Processes

List Processes of the given User in all Projects

GET

/gdc/account/profile/{user-id}/dataload/processes

Response

200 (OK)
Content-Type: application/json
{
    "processes" : {
        "items" : [ {
            "process" : {
                "name" : "some_transformation",
                "executables" : [ "graph/downloader.grf", "graph/gd_load.grf", "graph/jsons_parser.grf", "graph/run.grf", "graph/transform.grf" ],
                "links" : {
                    "self" : "/gdc/projects/{project-id}/dataload/processes/{process-id}",
                    "executions" : "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions"
                }
            }
        } ],
        "links": {
            "self": "/gdc/account/profile/{user-id}/dataload/processes"
        }
    }
}

Process

Get Process information

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}

Response

201 (Created)
Content-Type: application/json
{
    "process" : {
        "name" : "name",
        "executables" : [
            "graph/simple.grf",
            "graph/simpleNoParam.grf"
        ],
        "links" : {
            "self" : "/gdc/projects/{project-id}/dataload/processes/{process-id}",
            "executions" : "/gdc/{project-id}/dataload/processes/{process-id}/executions"
        }
    }
}

Update Process

PUT

/gdc/projects/{project-id}/dataload/processes/{process-id}

The workflow to update existing data loading process is the same as when you're creating new one. This resource requires updated process archive to be already uploaded to WebDAV.

Response

201 (Created)
Content-Type: application/json
{
    "process":{
        "name" : "Process Name",
        "executables" : [
            "graph/simple.grf",
            "graph/simpleNoParam.grf"
        ],
        "links" : {
            "self" : "/gdc/projects/{project-id}/dataload/processes/{process-id}",
            "executions" : "/gdc/{project-id}/dataload/processes/{process-id}/executions"
        }
    }
}

Update Process - multipart upload

POST

/gdc/projects/{project-id}/dataload/processes/{process-id}

Use this resource update existing data loading process with one single multipart http request. You have to archive (.zip) whole CloudConnect Project and send both metadata (json) and data as separated parts of the same request. Note: notice the use of POST method instead of PUT - POST is the only one supported for multipart uploads.

Remove Process

DELETE

/gdc/projects/{project-id}/dataload/processes/{process-id}

Response

204 (No Content)

Process Source

Download Process archive

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}/source

Response

303 (See Other)
Location: {url-from-which-process-archive-can-be-downloaded}

Process Executions

List Executions of a Process

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions{?offset,limit}

Parameters
Name Description Details
offset

offset of the first record

int, optional
default: 0
limit

maximal number of records

int, optional
default: 100

Response

200 (OK)
Content-Type: application/json
{
    "executions": {
        "paging": {
            "offset": 0,
            "count": 2
        },
        "items": [
            {
                "executionDetail": {
                    "status": "OK",
                    "created": "2014-02-27T08:25:40.327Z",
                    "started": "2014-02-27T08:25:51.490Z",
                    "updated": "2014-02-27T08:37:50.768Z",
                    "finished": "2014-02-27T08:37:50.640Z",
                    "links": {
                        "poll": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}",
                        "self": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/detail",
                        "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log"
                    }
                }
            },
            {
                "executionDetail": {
                    "status": "ERROR",
                    "created": "2014-02-24T19:00:35.999Z",
                    "started": "2014-02-24T19:00:39.155Z",
                    "updated": "2014-02-24T19:26:13.197Z",
                    "finished": "2014-02-24T19:26:13.060Z",
                    "error" : {
                        "errorCode" : "executor.error",
                        "message" : "Error message with some placeholders for parameters - like %s.",
                        "parameters" : [ "this one" ]
                    }
                    "links": {
                        "poll": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}",
                        "self": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/detail",
                        "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
                        "data": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/data"
                    }
                }
            }
        ]
    }
}

Execute Process

POST

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions{?offset,limit}

Response

201 (Created)
Content-Type: application/json
Location: /gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}
{
    "executionTask" : {
        "link" : {
            "poll" : "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}",
            "detail" : "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/detail"
        }
    }
}

Process Execution

Poll for basic Execution status

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}

Returns status code 202 Accepted if execution is still running and 204 No Content if it has already finished.

Response

204 (No Content)

Response

202 (Accepted)

Stop running Execution

DELETE

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}

Can be used to stop execution that's currently in progress.

Response

204 (No Content)

Process Execution Detail

Get Execution metadata

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/detail

Response

200 (OK)
Content-Type: application/json
{
    "executionDetail": {
        "status": "OK",
        "created": "2014-02-27T08:25:40.327Z",
        "started": "2014-02-27T08:25:51.490Z",
        "updated": "2014-02-27T08:37:50.768Z",
        "finished": "2014-02-27T08:37:50.640Z",
        "links": {
            "poll": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}",
            "self": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/detail",
            "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log"
        }
    }
}

Process Execution Log

Get Execution log

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log

Supports range requests that retrieve only part of execution log. If no range is given, the response status is 200 OK and response body contains full log.

Response

206 (Partial Content)
Content-Type: text/plain
Content-Length: 1000
Content-Range: 0-999/6971
The first 1000 bytes of execution log in text/plain

Process Execution Data

Download Execution data

GET

/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/data

Allows you to download data (both executables and any locally downloaded data) of a failed execution for inspection & debugging.

Response

302 (Found)
Location: {url-from-which-execution-data-can-be-downloaded}

Process Metadata

This API allows you to store key-value pairs in the Project for each Project. You can use those values by calling the individual resources.

Receive a list of metadata items

GET

/gdc/projects/{project-id}/dataload/metadata

Response

200 (OK)
Content-Type: application/json
{
    "metadataItems": {
         "paging": {
              "offset": 0,
              "count": 2
 },
    "links": {
    "self": "/gdc/projects/{project-id}/dataload/metadata"
 },
    "items": [
    {
        "metadataItem": {
            "key": "Key",
            "value": "Value",
            "links": {
                "self": "/gdc/projects/{project-id}/dataload/metadata/Key"
            }
        }
    },
{
        "metadataItem": {
            "key": "Name",
            "value": "Username",
            "links": {
                "self": "/gdc/projects/{project-id}/dataload/metadata/Name"
                    }
                }
            }
        ]
    }
}

Create and store new key-value pair

POST

/gdc/projects/{project-id}/dataload/metadata

Response

201 (Created)
Content-Type: application/json
{
    "metadataItem": {
        "key": "Test",
        "value": "Value"
    }
}

Process Metadata Item

Resource you can use to GET/UPDATE/DELETE individual metadata item

Receive single metadata item

GET

/gdc/projects/{project-id}/dataload/metadata/{key}

Response

200 (OK)
Content-Type: application/json
{
"metadataItem": {
    "key": "Key",
    "value": "Value",
    "links": {
        "self": "/gdc/projects/{project-id}/dataload/metadata/Key"
             }
    }
}

Receive single metadata item

PUT

/gdc/projects/{project-id}/dataload/metadata/{key}

Response

200 (OK)
Content-Type: application/json
{
"metadataItem": {
    "key": "Key",
    "value": "25",
    "links": {
        "self": "/gdc/projects/{project-id}/dataload/metadata/Key"
             }
    }
}

Delete single metadata item

DELETE

/gdc/projects/{project-id}/dataload/metadata/{key}

Response

204 (No Content)

Schedules

Schedules

List Project Schedules

GET

/gdc/projects/{project-id}/schedules{?offset,limit}

Parameters
Name Description Details
offset

offset of the first record

int, optional
default: 0
limit

maximal number of records

int, optional
default: 100

Response

200 (OK)
Content-Type: application/json
{
    "schedules": {
        "paging": {
            "offset": 0,
            "count": 1
        },
        "schedulesLink": "/gdc/projects/{project-id}/schedules",
        "items": [
            {
                "schedule": {
                    "type": "MSETL",
                    "state": "ENABLED",
                    "params": {
                        "PROCESS_ID": "{process-id}",
                        "EXECUTABLE": "Twitter/graph/twitter.grf"
                    },
                    "cron": "0 0 * * *",
                    "timezone": "UTC",
                    "nextExecutionTime": "2013-11-16T00:00:00.000Z",
                    "lastSuccessful": {
                        "execution": {
                            "startTime": "2013-11-15T00:00:40.355Z",
                            "endTime": "2013-11-15T00:00:49.030Z",
                            "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
                            "status": "OK",
                            "trigger": "CRON",
                            "links": {
                                "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{schedule-execution-id}"
                            }
                        }
                    },
                    "lastExecution": {
                        "execution": {
                            "startTime": "2013-11-15T00:00:40.355Z",
                            "endTime": "2013-11-15T00:00:49.030Z",
                            "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
                            "status": "OK",
                            "trigger": "CRON",
                            "links": {
                                "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{schedule-execution-id}"
                            }
                        }
                    },
                    "consecutiveFailedExecutionCount": 0,
                    "links": {
                        "self": "/gdc/projects/{project-id}/schedules/{schedule-id}",
                        "executions": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions"
                    }
                }
            }
        ]
    }
}

Schedule a Process

POST

/gdc/projects/{project-id}/schedules{?offset,limit}

To schedule Data Loading Process. Learn more about scheduling in following article.

Response

201 (Created)

Schedule

Get Schedule

GET

/gdc/projects/{project-id}/schedules/{schedule-id}

Update Schedule

PUT

/gdc/projects/{project-id}/schedules/{schedule-id}

Response

200 (OK)
Content-Type: application/json
{ 
    "schedule": {
        "type": "MSETL",
        "state": "ENABLED",
        "params": {
            "PROCESS_ID" : "{process-id}",
            "EXECUTABLE" : "graph/run.grf",
            "PARAM1_NAME" : "PARAM1_VALUE",
            "PARAM2_NAME" : "PARAM2_VALUE"
        },
        "cron": "0 15 27 7 *",
        "timezone": "UTC",
        "nextExecutionTime": "2013-11-16T00:00:00.000Z",
        "lastSuccessful": {
            "execution": {
                "startTime": "2013-11-15T00:00:40.355Z",
                "endTime": "2013-11-15T00:00:49.030Z",
                "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
                "status": "OK",
                "trigger": "CRON",
                "links": {
                    "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{schedule-execution-id}"
                }
            }
        },
        "lastExecution": {
            "execution": {
                "startTime": "2013-11-15T00:00:40.355Z",
                "endTime": "2013-11-15T00:00:49.030Z",
                "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
                "status": "OK",
                "trigger": "CRON",
                "links": {
                    "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{schedule-execution-id}"
                }
            }
        },
        "consecutiveFailedExecutionCount": 0,
        "links": {
            "self": "/gdc/projects/{project-id}/schedules/{schedule-id}",
            "executions": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions"
        }
    }
}

Schedule Executions

List Schedule Executions

GET

/gdc/projects/{project-id}/schedules/{schedule-id}/executions{?offset,limit}

Parameters
Name Description Details
offset

offset of the first record

int, optional
default: 0
limit

maximal number of records

int, optional
default: 100

Response

200 (OK)
Content-Type: application/json
{
    "executions": {
        "paging": {
            "offset": 0,
            "count": 2,
            "next": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions?offset=2&limit=2"
        },
        "items": [
            {
                "execution": {
                    "startTime": "2014-03-02T16:00:21.093Z",
                    "endTime": "2014-03-02T16:00:24.460Z",
                    "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{schedule-execution-id}/log",
                    "status": "OK",
                    "trigger": "CRON",
                    "links": {
                        "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{schedule-execution-id}"
                    },
                    "createdTime": "2014-03-02T16:00:18.963Z"
                }
            },
            {
                "execution": {
                    "startTime": "2014-03-02T15:00:20.184Z",
                    "endTime": "2014-03-02T15:00:23.320Z",
                    "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
                    "status": "OK",
                    "trigger": "CRON",
                    "links": {
                        "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{execution-id}"
                    },
                    "createdTime": "2014-03-02T15:00:18.410Z"
                }
            }
        ]
    }
}

Execute Schedule

POST

/gdc/projects/{project-id}/schedules/{schedule-id}/executions{?offset,limit}

Schedule will be placed in execution queue and will run as soon as possible.

Response

200 (OK)
Content-Type: application/json
{
    "execution": {
        "status": "SCHEDULED",
        "trigger": "MANUAL",
        "links": {
            "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{schedule-execution-id}"
        }
    }
}

Delete Schedule

DELETE

/gdc/projects/{project-id}/schedules/{schedule-id}/executions{?offset,limit}

Response

204 (No Content)

Schedule Execution

Get Execution

GET

/gdc/projects/{project-id}/schedules/{schedule-id}/execution

Response

200 (OK)
Content-Type: application/json
{
    "execution": {
        "startTime": "2014-03-02T15:00:20.184Z",
        "endTime": "2014-03-02T15:00:23.320Z",
        "log": "/gdc/projects/{project-id}/dataload/processes/{process-id}/executions/{execution-id}/log",
        "status": "OK",
        "trigger": "CRON",
        "links": {
            "self": "/gdc/projects/{project-id}/schedules/{schedule-id}/executions/{execution-id}"
        },
        "createdTime": "2014-03-02T15:00:18.410Z"
    }
}

CloudConnect Zendesk Connector

Download task properties

  • startDate (DATETIMEISO), download all tickets from this date on

  • zendeskDomain (uri), Zendesk's endpoint

POST

/gdc/projects/{project-id}/dataload/download/zendesk/downloadTasks

To create download task

Response

201 (Created)
{"asyncTask":
    {"link":{
        "poll":"/gdc/projects/{project-id}/dataload/download/zendesk/downloadTasks/{task-id}"}
    }
}

GET

/gdc/projects/{project-id}/dataload/download/zendesk/downloadTasks/{task-id}

To get download task (task running)

Response

202 (Accepted)

CloudConnect Google Analytics Connector

Download task properties

  • credentials

    • username - GA user name
    • password - GA user password
  • definition

    • ids - unique table ID, format: ga:XXXX (where XXXX is the Analytics profile ID), required field
    • start date - first date for which user requests data, format: YYYY-MM-DD, required field
    • end date - last date for which user requests data, format: YYYY-MM-DD, required field
    • metrics - list of comma-separated metrics, required field
    • dimensions - list of comma-separated dimensions
    • filters - dimension and metric filters that restricts data returned for user request
    • segment - segments the data for user's request

POST

/gdc/projects/{project-id}/dataload/download/googleanalytics/downloadTasks

Create download task

Response

201 (Created)
{
    "asyncTask": {
        "link": {
            "poll": "/gdc/projects/{project-id}/dataload/download/googleanalytics/downloadTasks/{task-id}"
        }
    }
}

GET

/gdc/projects/{project-id}/dataload/download/googleanalytics/downloadTasks/{task-id}

Get download task (running)

Response

202 (Accepted)

Facebook tokens refreshing

In order to call the Facebook Graph API, it is necessary to have a valid OAuth 2.0 token, which is valid for 60 days only after it has been issued. The purpose of this API is the (per project) management of such Facebook tokens, as well as sending notifications to the user when the token to his account is about to expire.

POST

/gdc/projects/{project-id}/dataload/download/facebook/tokens

Using this request, you can create a new Facebook token request

Response

201 (Created)
{"uri":"/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}"}

GET

/gdc/projects/{project-id}/dataload/download/facebook/tokens

Obtain all Facebook tokens for a particular project

Response

200 (OK)
{
  "facebookTokens" : {
    "items" : [
      "/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}",
      "/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}" ]
  }
}

GET

/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}

Obtain a specific Facebook token

Response

200 (OK)
{
  "facebookToken" : {
    "id" : "/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}",
    "email" : "example@example.com",
    "label" : "Facebook account A",
    "facebookAccountId" : "xxffaa5",
    "applicationId" : "123456",
    "issued" : "2013-05-09T11:37:32.778Z",
    "expired" : null,
    "token" : "Some token issued by Facebook",
    "notificationsEnabled" : true,
    "state" : "LONGLIVED",
    "scope" : [ ]
  }
}

PUT

/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}

Update a Facebook token

Response

204 (No Content)

DELETE

/gdc/projects/{project-id}/dataload/download/facebook/tokens/{token-id}

Delete a facebook token

Response

204 (No Content)

Zendesk Connector

Following resources are related to the Zendesk integration connector.

POST

/gdc/projects/{project_id}/connectors/zendesk3/integration

Create new integration by this request

Response

201 (Created)

GET

/gdc/projects/{project_id}/connectors/zendesk3/integration

This Resource gives you existing integration

Response

200 (OK)
{
  "integration" : {
    "projectTemplate" : "/projectTemplates/ZendeskAnalytics/9",
    "active" : false,
    "lastFinishedProcess" : null,
    "lastSuccessfulProcess" : null,
    "runningProcess" : null,
    "links" : {
      "self" : "/gdc/projects/{project-id}/connectors/zendesk3/integration",
      "processes" : "/gdc/projects/{project-id}/connectors/zendesk3/integration/processes",
      "config" : "/gdc/projects/{project-id}/connectors/zendesk3/integration/config"
    },
    "ui" : { }
  }
}

PUT

/gdc/projects/{project_id}/connectors/zendesk3/integration

To update the existing integration

Response

200 (OK)

DELETE

/gdc/projects/{project_id}/connectors/zendesk3/integration

To delete the existing integration

Response

204 (No Content)

GET

/gdc/gdc/projects/{project_id}/connectors/zendesk3/integration/config

To get the navigation structure for existing integration

Response

200 (OK)
{
  "config" : {
    "settingsLink" : "/gdc/projects/{project-id}/connectors/zendesk3/integration/config/settings"
  }
}

GET

/gdc/projects/{project_id}/connectors/zendesk3/integration/config/settings

To get the config for existing integration

Response

200 (OK)
{
  "settings" : {
    "apiUrl" : null,
    "syncTime" : "12am",
    "syncTimeZone" : "America/Los_Angeles",
    "type" : "plus",
    "enterpriseLoadInterval" : 60
  }
}

PUT

/gdc/projects/{project_id}/connectors/zendesk3/integration/config/settings

To update the config for existing integration

  • apiURL: Zendesk API endpoint

Response

204 (No Content)

POST

/gdc/projects/{project_id}/connectors/zendesk3/integration/processes

To create new integration process

Response

201 (Created)

Zendesk 4 Connector

POST

/gdc/projects/{projectName}/connectors/zendesk4/integration

Create integration resource

Response

201 (Created)
{
    "integration" : {
        "projectTemplate" : "/projectTemplates/ZendeskAnalytics/10",
        "active" : true,
        "lastFinishedProcess" : null,
        "lastSuccessfulProcess" : null,
        "runningProcess" : null,
        "links" : {
            "self" : "/gdc/projects/{project-id}/connectors/zendesk4/integration",
            "processes" : "/gdc/projects/{project-id}/connectors/zendesk4/integration/processes",
            "settings" : "/gdc/projects/{project-id}/connectors/zendesk4/integration/settings",
        },
        "ui" : { }
    }
}

GET

/gdc/projects/{projectName}/connectors/zendesk4/integration

Retrieve integration resource

Response

200 (OK)
{
    "integration" : {
        "projectTemplate" : "/projectTemplates/ZendeskAnalytics/10",
        "active" : true,
        "lastFinishedProcess" : null,
        "lastSuccessfulProcess" : null,
        "runningProcess" : null,
        "links" : {
            "self" : "/gdc/projects/{project-id}/connectors/zendesk4/integration",
            "processes" : "/gdc/projects/{project-id}/connectors/zendesk4/integration/processes",
            "settings" : "/gdc/projects/{project-id}/connectors/zendesk4/integration/settings"
        },
        "ui" : { }
    }
}

PUT

/gdc/projects/{projectName}/connectors/zendesk4/integration

Update integration resource

Response

200 (OK)
{
    "integration" : {
        "projectTemplate" : "/projectTemplates/ZendeskAnalytics/10",
        "active" : true,
        "lastFinishedProcess" : null,
        "lastSuccessfulProcess" : null,
        "runningProcess" : null,
        "links" : {
            "self" : "/gdc/projects/{project-id}/connectors/zendesk4/integration",
            "processes" : "/gdc/projects/{project-id}/connectors/zendesk4/integration/processes",
            "settings" : "/gdc/projects/{project-id}/connectors/zendesk4/integration/settings",
        },
        "ui" : { }
    }
}

POST

/gdc/projects/{projectName}/connectors/zendesk4/integration/processes

Create integration process

Response

201 (Created)
{
    "uri": "/gdc/projects/{project-id}/connectors/zendesk4/integration/processes/{process-id}"
}

GET

/gdc/projects/{projectName}/connectors/zendesk4/integration/settings

Retrieve integration settings

Response

200 (OK)
Content-Type: application/json
{
    "settings": {
        "apiUrl": "https://somedomain.zendesk.com",
        "syncTime": "10am",
        "syncTimeZone": "Europe/Prague",
        "type": "plus"
    }
}

{
    "settings": {
        "apiUrl": "https://somedomain.zendesk.com",
        "type": "enterprise"
    }
}

PUT

/gdc/projects/{projectName}/connectors/zendesk4/integration/settings

Update integration settings

Response

204 (No Content)

White Labeling

Organization administrators and owners can use the following resources to customize the appearance of their organzations.

Manage white labeling

  • noReplyEmail (required, string) - Email address that scheduled reports are sent from

  • registrationEmail (required, string) - Email address that registration confirmation emails and forgotten password emails are sent from.

  • invitationEmail (required, string) - Email address that project invitation emails are sent from.

  • bccEmail (required, string) - Email address that is blind copied on invitation emails.

  • supportEmail (required, string) - (mailSettings section) Email address that emails to support are sent to. Also appears in the body of some emails.

  • supportPhone (required, string) - Phone number for reaching customer support. This phone number appears in email templates.

  • applicationTitle (required, string, <My Company> Analytics) - Text in the browser title bar, or tab title.

  • faviconUrl (optional, fully qualified or relative URL) - Image that appears in the browser address bar. Format: 16 x 16, 32 x 32, 48 x 48, or 64 x 64 px; ICO 

  • orgnizationName (required, string, GoodData Corporation) - Name of the organization on the GoodData platform. This value is used in the copyright text and in the body of emails generated by the Portal.

  • displayFlashNews (required, boolean) - Specify whether to display status bar that appears on Portal after a new GoodData platform release. This status bar links to information published by GoodData. Can be disabled.

  • logoUrl (required, fully qualified or relative URL) - Logo displayed in the top-left corner of the Portal. Format: 120px x 25 px, PNG

  • displayProjects (required, boolean) - Specify whether users can select projects on the project picker menu located in Account > Active Projects. Can be disabled.

  • displayAccountPage (required, boolean) - Specify whether users can review their account details on the Account menu. Can be disabled.

  • supportEmail(optional, string) - (portalSettings section) Email that tickets are sent to when users click Help > Submit Ticket. Can be disabled.

  • supportForumUrl (optional, fully qualified or relative URL) - URL that users are directed to when they click Help > Visit Support, or Help in the dashboard footer. Can be disabled.

  • privacyPolicyUrl (optional, fully qualified or relative URL) - URL that users are directed to when they click Privacy Policy in the Portal footer, or Account > Personal Information > privacy policy. Can be disabled.

  • documentationUrl (optional, fully qualified or relative URL) - URL that users are directed to when they click Help in the Portal footer, or click Help > Documentation. Can be disabled.

  • securityStatmentUrl (optional, fully qualified or relative URL) - URL that users are directed to when they click Security Statement in the Portal footer. Can be disabled.

  • termsofUseUrl (optional, fully qualified or relative URL) - URL that users are directed to when they click Terms of Use in the Portal footer. Can be disabled.

  • trustUrl (optional, fully qualified or relative URL) - URL that users are directed to when they click Trust in the Portal footer. Can be disabled.

  • appleTouchIconUrl (optional, fully qualified or relative URL) - The desktop icon that iOS users see when they save a GoodData page to desktop. Provide a link to this icon. Format: 114 x 114px, PNG

  • applicationBackgroundColor (optional, HTML color code in hex) - Custom background color for the dashboard. This color is not applied to the login, logout, registration, invitation or confirmation pages. If you specify both a dashboard image and a color, the image is displayed on top of the background color.

  • hideRegistration (optional, boolean) - Hide the link to the registration form on the Login page. This stops users from registering without being invited.

  • largeLogoUrl (optional, fully qualified or relative URL) - Logo that appears on the Login and Registration pages. Format: 130px maximum height, 470px maximum width, PNG preferred

  • brandColor (optional, HTML color code in hex) - Narrow strip of color on the top of the Login and Registration pages.

  • headerColor (optional, HTML color code in hex) - Custom color for the dashboard header.

  • activeColor (optional, HTML color code in hex) - Custom underline color on active navigation elements.

  • headerTextColor (optional, HTML color code in hex) - Custom color for the text on the dashboard header.

Retrieve white labeling settings

GET

/gdc/organizations/{organization_name}/settings

Parameters
Name Description Details
organization_name

The name of the organization where white labeling is applied.

string, required

Response

200 (OK)
{
    "settings":{
        "mailSettings":{
            "noReplyEmail":"1noreply@example.com",
            "registrationEmail":"2reg@example.com",
            "invitationEmail":"3inv@example.com",
            "bccEmail":"4bcc@example.com",
            "supportEmail":"5support@example.com",
            "supportPhone":"+420 123 456 789"
        },
        "portalSettings":{
            "applicationTitle":"Custom analytics",
            "faviconUrl":"/favicon",
            "organizationName":"My organization",
            "displayFlashNews":false,
            "logoUrl":"http://www.website.com/mynewlogo.jpg",
            "displayProjects":false,
            "displayAccountPage":true,
            "supportEmail":"support@example.com",
            "supportForumUrl":"/link/to/support/forums",
            "privacyPolicyUrl":"/privacyPolicy",
            "documentationUrl":"/help/link",
            "securityStatementUrl":"/security",
            "termsOfUseUrl":"/tos",
            "trustUrl":"/trust",
            "appleTouchIconUrl":"/icon.png",
            "applicationBackgroundColor":"#999",
            "hideRegistration":"true | false",
            "largeLogoUrl":"http://www.website.com/largelogo.jpg",
            "brandColor":"#999",
            "headerColor":"#FF0040", 
            "activeColor":"#F7FE2E",
            "headerTextColor":"#610B38"
          }
     }
}

Update white labeling settings

PUT

/gdc/organizations/{organization_name}/settings

Parameters
Name Description Details
organization_name

The name of the organization where white labeling is applied.

string, required

Response

204 (No Content)

Agile Data Warehousing Service

ADS is an Agile Data Warehousing Service fully hosted by GoodData. Using the ADS API you are able to list, create and update the ADS Instances. Remember that you need a special authorization token to create new ADS instance.

GET

/gdc/dss/instances

API resource for retrieving the list of all available ADS instances.

Response

200 (OK)
Content-Type: application/json
Accept: application/json
{
  "dssInstances" : {
    "items" : [ {
      "dssInstance" : {
        "title" : "Storage",
        "description" : "Testing Storage",
        "status" : "ENABLED",
        "authorizationToken" : “token",
        "created" : "2014-03-17T13:02:39.000Z",
        "updated" : "2014-03-17T13:02:41.000Z",
        "createdBy" : "/gdc/account/profile/{profile-id}",
        "updatedBy" : "/gdc/account/profile/{profile-id}",
        "links" : {
          "self" : "/gdc/dss/instances/{instance-id}",
          "parent" : "/gdc/dss/instances",
          "users" : "/gdc/dss/instances/{instance-id}/users",
          "jdbc" : "/gdc/dss/instances/{instance-id}/jdbc"
        }
      }
    }, {
      "dssInstance" : {
        "title" : "Salesforce",
        "description" : "Test",
        "status" : "ENABLED",
        "authorizationToken" : “token",
        "created" : "2014-04-09T22:10:26.000Z",
        "updated" : "2014-04-09T22:10:26.000Z",
        "createdBy" : "/gdc/account/profile/{profile-id}",
        "updatedBy" : "/gdc/account/profile/{profile-id}",
        "links" : {
          "self" : "/gdc/dss/instances/{instance-id}",
          "parent" : "/gdc/dss/instances",
          "users" : "/gdc/dss/instances/{instance-id}/users",
          "jdbc" : "/gdc/dss/instances/{instance-id}/jdbc"
        }
      }
    } ],
    "links" : {
      "parent" : "/gdc/dss",
      "self" : "/gdc/dss/instances"
    }
  }
}

POST

/gdc/dss/instances

Resource to create new ADS Instance. Use the following payload. You need to have ADS Token that allows you to create a ADS Instance.

Response

202 (Accepted)
Content-Type: application/json
Accept: application/json
         {
  "asyncTask" : {
    "links" : {
      "poll" : "/gdc/dss/executions/{execution-id}"
        }
        }
        }

GET

/gdc/dss/instances/{instance-id}

Retrieve details about specific ADS instance.

Response

200 (OK)
Content-Type: application/json
Content-type: application/json
    {
      "dssInstance" : {
        "title" : "Test",
        "description" : "Storage",
        "status" : "ENABLED",
        "authorizationToken" : "{Token}",
        "created" : "2014-05-05T08:27:33.000Z",
        "updated" : "2014-05-05T08:27:34.000Z",
        "createdBy" : "/gdc/account/profile/{profile-id}",
        "updatedBy" : "/gdc/account/profile/{profile-id}",
        "links" : {
          "self" : "/gdc/dss/instances/{instance-id}",
          "parent" : "/gdc/dss/instances",
          "users" : "/gdc/dss/instances/{instance-id}/users",
          "jdbc" : "/gdc/dss/instances/{instance-id}/jdbc"
        }
      }
    }

PUT

/gdc/dss/instances/{instance-id}

Resource for updating the ADS Instance.

Response

204 (No Content)

DELETE

/gdc/dss/instances/{instance-id}

Use this resource to DELETE given ADS Instance

Response

204 (No Content)

GET

/gdc/dss/executions/{taskId}

Poll this resource to GET the ADS instance creation task detail

Response

202 (Accepted)
Content-Type: application/json
Content-type: application/json
{
  "asyncTask" : {
    "links" : {
      "poll" : "/gdc/dss/executions/{execution-id}"
    }
  }
}

Response

201 (Created)
Content-Type: application/json
Content-type: application/json
{
    "asyncTask": {
                "links": {
                    "dssInstance": "/gdc/dss/instances/{instance-id}”,
                    “user”: “user URI”,
                    “users”: “URI of users in DSS Instance"
                }
         }
  }