API Reference Guide. API Version 1. Copyright Platfora 2016

Transcription

1 API Reference Guide API Version 1 Copyright Platfora 2016 Last Updated: 10:05 a.m. April 21, 2016

2 Contents Document Conventions... 5 Contact Platfora Support...6 Copyright Notices... 6 Chapter 1: Using the Platfora REST API... 8 About the Platfora REST API... 8 Authentication... 9 About Versioning... 9 Character Encoding...10 Common Resource Attributes...10 Common Call Metadata HTTP Response Codes Chapter 2: users Resource Overview...17 List All Users...18 GET a User...20 Create a User...21 PATCH a User Chapter 3: groups Resource...26 Overview...26 List All groups GET a group POST a New group Update a group Chapter 4: datasources Resource...36 Overview...36 List All Data Sources List a Data Source Create a Data Source...45 Chapter 5: datasets Resource Overview...49 List All Datasets List a Dataset...96 Create Datasets... 97

3 API Reference Guide - Contents Chapter 6: lenses Resource Overview List All Lenses List a Lens Create Lenses Chapter 7: lensbuilds Resource Overview POST a Lens Build GET a Lens Build Chapter 8: vizboards Resource Overview List Vizboards List a Vizboard Create Vizboard Chapter 9: labels Resource Overview List All Labels List a Label Create a Label Update a Label Delete a Particular Label Chapter 10: labelassignments Resource Overview List All Label Assignments List a Label Assignment Create a Label Assignment Delete a Particular Label Assignment Chapter 11: query Resource Overview Query a Lens Lens Query Language Reference SELECT Statement Chapter 12: workflows Resource Overview List All Workflows List a Specific Workflow Page 3

4 API Reference Guide - Contents Create a Workflow Modify an Existing Workflow Delete a Workflow Chapter 13: permissions Resource Overview List All Permissions PUT a permission PATCH a permission Chapter 14: renderjobs Resource Overview List All Render Jobs List a Specific Render Job Create a Render job Cancel a Render Job Page 4

5 Preface This guide provides information and instructions for using the REST API provided by Platfora. This guide is intended for API programmers with knowledge of APIs and the Platfora software. Knowledge of Python may also be useful. Document Conventions This documentation uses certain text conventions for language syntax and code examples. Convention Usage Example $ Command-line prompt - proceeds a command to be entered in a command-line terminal session. $ sudo Command-line prompt for a command that requires root permissions (commands will be prefixed with sudo). $ ls $ sudo yum install open-jdk-1.7 UPPERCASE italics [ (square brackets)... (elipsis) Function names and keywords are shown in all uppercase for readability, but keywords are caseinsensitive (can be written in upper or lower case). Italics indicate a usersupplied argument or variable. Square brackets denote optional syntax items. An elipsis denotes a syntax item that can be repeated any number of times. SUM(page_views) SUM(field_name) CONCAT(string_expression[,...) CONCAT(string_expression[,...) Page 5

6 API Reference Guide - Introduction Contact Platfora Support For technical support, you can send an to: [email protected] Or visit the Platfora support site for the most up-to-date product news, knowledge base articles, and product tips. To access the support portal, you must have a valid support agreement with Platfora. Please contact your Platfora sales representative for details about obtaining a valid support agreement or with questions about your account. Copyright Notices Copyright Platfora Corporation. All rights reserved. Platfora believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. PLATFORA CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any Platfora software described in this publication requires an applicable software license. Platfora, You Should Know, Interest Driven Pipeline, Fractal Cache, and Adaptive Job Synthesis are trademarks of the Platfora Corporation. Apache Hadoop and Apache Hive are trademarks of the Apache Software Foundation. All other trademarks used herein are the property of their respective owners. Embedded Software Copyrights and License Agreements Platfora contains the following open source and third-party proprietary software subject to their respective copyrights and license agreements: Apache Hive PDK dom4j freemarker GeoNames Google Maps API Apache Jandex Page 6

7 API Reference Guide - Introduction Apache POI javassist javax.servlet Mortbay Jetty OWASP CSRFGuard 3 PostgreSQL JDBC Scala sjsxp : Unboundid Tableau Page 7

8 Chapter 1 Using the Platfora REST API Platfora has a built-in Representational State Transfer (REST) API which consists of several calls that can be used to integrate with Platfora using HTTP. This is the web services layer upon which all integrations with Platfora are performed. Topics: About the Platfora REST API Authentication About Versioning Character Encoding Common Resource Attributes Common Call Metadata HTTP Response Codes About the Platfora REST API This section describes some rules and guidelines to consider when using the REST API. From your Platfora application, you can use the interactive REST API Browser to explore and test Platfora's REST Page 8

9 API Reference Guide - Using the Platfora REST API APIs. To visit the browser, log into your Platfora application and click REST API Browser on the System page. With a few exceptions, the API endpoints refer to individual resources or collections of resources (entities/objects), not actions. Resource objects are represented in JSON. When the API calls create, modify, or delete objects in Platfora, they usually impact the Platfora metadata catalog. Some calls may also submit jobs that cause Platfora to interact with the Hadoop cluster. The API is sessionless and stateless. Timestamps use ISO 8601 in UTC. For example "createdtimestamp": " T18:02:24.343Z" Return results are non-cacheable. The HTTP Location header in responses to POST requests is set to the URL for the newly created object. Authentication Platfora uses HTTP Basic authentication over HTTPS to authenticate user credentials provided in the API call. The caller's Platfora permissions determine the actions the caller is authorized to perform with Platfora. Platfora recommends creating one or more dedicated user accounts for API calls. About Versioning The Platfora REST API is versioned, and may have both major and minor version changes. It uses a major.minor numbering format. Minor versions indicate that only data or methods have been added. For well-written API clients, a minor version change is backward compatible with the major version. For example, version X.1 is backward compatible with version X.0. Major versions indicate that something has changed such that clients using the affected API calls will need modification. For example, parameters, URL paths, or the shape of input or output data might have Page 9

10 API Reference Guide - Using the Platfora REST API changed, or features or data have been removed. The URL for each resource endpoint contains the major version number. For example, /api/v1/datasets/ uses version 1.x. The full major.minor version is included in response bodies using the "apiversion" parameter in the metadata part of the payload. For example: "apiversion": "1.0" Character Encoding The REST API expects and returns UTF-8 character encoding. No other character encoding is supported. Common Resource Attributes Platfora resources share a set of common attributes. Common attributes include identifiers, version information, and object history.this section describes the attributes found on all Platfora resources. Platfora REST APIs return several common attributes in a return body (GET and POST). These attributes include the following: Attribute id version name history namespace objectpermissions Description A unique identifier. Platfora assigns this value, callers cannot modify it. The object's version. Platfora assigns this value, callers cannot modify it. An object's unique name. All objects require a name. Callers can read and write names. An array of History objects. Specifies the namespace in which the object resides. An object's unique namespace. All objects require a namespace. Callers can read and write namespaces. A read-only structure containing the permission set. These are users or groups that have access to the resource: Owner Create Edit DataAccess Viewer Page 10

11 API Reference Guide - Using the Platfora REST API Attribute href Description A read-only reference to the object. A History object is read-only structure with the following values: Attribute lifecyclestage Description An enumeration indicating an object's stage. This is one of: modified created deleted replaces version time user The version this object replaces. The object's new version. Platfora assigns this value, callers cannot modify it. Time stamp for the stage. A read-only structure identifying the last user to change the object. Common Call Metadata Each REST API request and response uses the exact same payload which contains metadata about the resource objects it contains. Inside each payload is the operation of the request, such as the data for creating a data source in the POST to the datasources resource, or the response from Platfora, such as the list of datasets from a GET to the datasets resource. Since all API requests and responses use the same structure, clients can reuse logic when creating requests and processing responses. Sample Payload for a Request The text below is the payload to use when creating the body of a POST request. "data": resource_objects_in_request Sample Payload for a Response The text below is the payload for the response from a GET /api/v1/datasources/id "_links": Page 11

12 API Reference Guide - Using the Platfora REST API "self": "href": " "rel": "self", "title": "Lenses" "_metadata": "apiversion": "1.0", "code": 20000, "count": 1, "developermessage": "Successful call to get list of lenses.", "error": false, "maxrecords": 1, "message": "Successful call to get list of lenses.", "messagei18n": "Successful call to get list of lenses.", "offset": 0, "requesttime": " T17:24:26.606Z", "responsetime": " T17:24:27.896Z", "status": 200, "valuemap": "data": "datasets": [ resource_objects_from_server "_links" Section Parameters REST API responses always include the _links section. Requests should not use this section. self Required for responses. This is a container for a collection of parameters that inform the API client Example: "self": list_of_parameters href The URL that was used in the request that caused this response. Example: "href": " rel Relationship to the call. Example: "rel": "self", title Resource title. Page 12

13 API Reference Guide - Using the Platfora REST API Example: "title": "Lenses" "_metadata" Section Parameters All parameters below are required for REST API responses. Requests should use the following text for the _metadata section: "_metadata": apiversion The version of the REST API used for the request or response. Example: "apiversion": "1.0", code A numeric code that helps Platfora Customer Support troubleshoot errors. Primarily for Platfora use. Example: "code": "20100", count The number of resource objects included in the request or response. Example: "count": "2", developermessage A string text message that helps Platfora Customer Support troubleshoot errors. Primarily for Platfora use. Example: "developermessage": "VizBoard 'My VizBoard' was created at T17:23:10.254Z by error Indicates whether or not the server encountered an error processing the request. Example when the server successfully processes the request: "error": "false", Example when the server returns an error: "error": "true", limit Indicates the number of resource objects that were limited in the response. Useful when the request used the limit URL parameter to limit the number of returned objects. Example: "limit": "2", maxrecords Indicates the maximum number of resource objects allowed in the response. This value comes from the maxrecords URL parameter in the request. Note that the actual numbef of objects in the response may be less. For exampe, there might be fewer objects than the maximum allowed, or the server might impose a lower limit than the number indicated in the maxrecords URL parameter in the request to protect resources. Page 13

14 API Reference Guide - Using the Platfora REST API Example: "maxrecords": "121", message Message returned from the server in English. This may include either informational or error text. Example: "message": "VizBoard \"My VizBoard\" created.", messagei18n Message returned from the server in a localized language (for future support). This may include either informational or error text. Example: "messagei18n": "VizBoard \"$name\" created.", moreinfo A URL where you can find more information about the code that was returned. Example: "moreinfo": " offset Indicates the number of resource objects that were skipped before listing the objects in the response. Useful when the request used the offset URL parameter to skip some objects. Example: "offset": "0", requesttime The time that the server saw the request, in ISO 8601 format in Coordinated Universal Time (UTC). You can specify "now" with: datetime.utcnow().strftime("%y-%m-%dt%h:%m:%s.%fz") Example: "requesttime": " T14:34:32.198Z", responsetime The time that the server sent the response, in ISO 8601 format in Coordinated Universal Time (UTC). You can specify "now" with: datetime.utcnow().strftime("%y-%m-%dt%h:%m:%s.%fz") Example: "responsetime": " T14:39:53.296Z", status The HTTP response code, such as 201. The status should match the HTTP status code in the response sent to the client. Example when the server successfully processed the request and created a new resource: "status": "201", valuemap Not used next Page 14

15 API Reference Guide - Using the Platfora REST API When the response returns a subset of resource objects due to the offset and limit parameters (a paginated result), the next parameter is includes a URL to make it easy for the client to get the next set (page) of results. Example: "next": "/api/v2/datasets?offset=2&limit=2 "data" Section This section contains the resource object(s) in the request or response. For more information on the structure of this section for each resource object type, see the REST API documentation for each resource type, such as datasets. HTTP Response Codes Each REST API response uses an HTTP response code that indicates the status of the API call request. HTTP Response Codes HTTP Response Code Supported HTTP Methods Description 200 GET The GET request successfully returned results or DELETE is successful. For a DELETE, a metadata structure is not returned. 201 POST The resource in the POST request was successfully created. 400 GET, POST There was an unknown problem with the request. Platfora uses this response code when it doesn't have a more specific 4xx response code to return. 401 GET, POST Unauthorized request. The request requires user authentication. Retry with authentication credentials. 403 GET, POST The credentials were authenticated but the caller is not authorized to access the resource. 404 GET, POST The requested resource was not found because the URL is invalid due to specifying an invalid path. For example, 404 is returned for a GET /api/v1/datasetssss/1 request. 409 POST The request was not performed because it conflicts with existing data in the metadata catalog. For example, this is returned when the request tries to create a new object with the same name as an existing one, or when it tries to modify or delete an object whose version is out of date. Page 15

16 API Reference Guide - Using the Platfora REST API HTTP Response Code Supported HTTP Methods Description 410 GET The request attempted to access a resource that does not exist in Platfora, or the object references a Platfora object that does not exist. 412 POST The Body contents of the request are invalid in some way. For example, it may be missing a field, use an invalid field format, contain unparseable input, or contain referenced entities that do not exist. 500 GET, POST There was an unknown problem with Platfora. Platfora uses this response code when it doesn't have a more specific 5xx response code to return that indicates a problem with the Platfora server. For example, it includes uncaught exceptions due to invalid input data. 503 GET, POST The Platfora server did not respond. Example Error Response The text below is returned in the HTTP response Body when a GET call is made for a data source of a particular ID that does not exist. The call returned a 410 code. "_metadata": "apiversion": "1.0", "code": " ", "count": 0, "developermessage": "Catalog object not found when handling request to /api/v1/datasources. Details: DataSource not found: ", "error": true, "maxrecords": 0, "message": "Catalog object not found when handling request to / api/v1/datasources", "messagei18n": "Catalog object not found when handling request to /api/v1/datasources", "offset": -1, "requesttime": " T00:20:35.361Z", "responsetime": " T00:20:35.364Z", "status": 410, "valuemap": "id": " " "data": "datasources": [ Page 16

17 Chapter 2 users Resource Use the users resource to create a data source or list data sources. Topics: Overview List All Users GET a User Create a User PATCH a User Overview The users resource represents a user account in Platfora. You can create users locally in Platfora or reuse users defined through an external directory service such as LDAP. A user has an associated systemrole that grants permissions to Platfora objects. Administrators can also grant users rights by assigning them group membership. All users belong to the system defined Everyone group. A user's effectiverole is computed value after considering all their group memberships; The most permissive role takes precedence. You can create a user but you cannot delete one. You can disable a user. Disabling a user prevents the user from interacting with Platfora either through the browser application or through another client. A user resource has the following attributes: Attribute name disabled systemrole Description A name for display in the UI but not for logging into the system. Status of the user. This is either false or true. This is the system role assigned directly to the user. groupmembershipsan array describing each group the user belongs to. Each member of the array has an href and an id field. Page 17

18 API Reference Guide - users Resource Attribute effectiverole href id type username Description The derived system role when taking into consideration the user's group memberships. A quick link to the user. The internal identifier for the user. Where the user is defined. This can be either LOCAL to Platfora or from an EXTERNAL directory service. The name used to log into the Platfora application. List All Users Use the GET method to retrieve and list the users currently configured in Platfora. URL /api/v1/users HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all users defined in Platfora: Page 18

19 API Reference Guide - users Resource "data": "users": [ "name": "Ariel Riopel", "disabled": false, "systemrole": "SuperAdmin", "externalid": "[email protected]", "effectiverole": "SuperAdmin", "href": " users/605441", "id": "605441", "type": "EXTERNAL", "username": "[email protected]" "name": "hari_analyst", "disabled": false, "systemrole": "Viewer", "groupmemberships": [ "href": " v1/groups/-1", "id": "-1" "effectiverole": "Viewer", "href": " users/678212", "id": "678212", "type": "LOCAL", "username": "hari_analyst" "name": "RT_Viewer", "disabled": false, "systemrole": "Viewer", "groupmemberships": [ "href": " v1/groups/-1", "id": "-1" "effectiverole": "Viewer", "href": " users/738973", "id": "738973", "type": "LOCAL", "username": "rt_viewer" "_metadata": Page 19

20 API Reference Guide - users Resource... "_links":... GET a User Use the GET method to retrieve a user currently configured in Platfora. URL /api/v1/users/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call You must supply an id in the URL. For GET requests, the body of the HTTP request should be empty. Success Response This response returns the user structure from Platfora: "data": "users": [ "name": "Ariel Riopel", Page 20

21 API Reference Guide - users Resource "disabled": false, "systemrole": "SuperAdmin", "externalid": "[email protected]", "effectiverole": "SuperAdmin", "href": " users/605441", "id": "605441", "type": "EXTERNAL", "username": "[email protected]" "_metadata":... "_links":... Create a User Use the POST method to create a new user in Platfora. URL /api/v1/users HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 21

22 API Reference Guide - users Resource Data Parameters The POST supports a JSON body containing the following: Attribute name disabled systemrole Description A name for display in the UI but not for logging into the system. This is required. Status of the user. This is either false or true. This is optional. If you don't specify this value, this is set to false by default. This is the system role assigned directly to the user. This is optional. If you don't specify this value, this is set to Viewer by default. groupmembershipsan array describing each group the user belongs to. Each member of the array has an href and an id field. This is optional. All user are added to the Everyone group by default. type username password Where the user is defined. This can be either LOCAL to Platfora or from an EXTERNAL directory service. This is optional. If you don't specify this value, this is set to LOCAL by default. A unique name used to log into the Platfora application. This is required and must be unique. A password to log into the Platfora application. This is required. Sample Call Body "data": "users": [ "name": "Laura Higgins", "username": "[email protected]", "password": "1234" Success Response This response returns the newly created user structure from Platfora: "data": "users": [ Page 22

23 API Reference Guide - users Resource "name": "Laura Higgins", "disabled": false, "systemrole": "Viewer", "groupmemberships": [ "href": " v1/groups/-1", "id": "-1" "effectiverole": "Viewer", "href": " users/ ", "id": " ", "type": "LOCAL", "username": "[email protected]" "_metadata":... "_links":... PATCH a User Use the PATCH method to update a Platfora user account. URL /api/v1/users HTTP Method PATCH Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 23

24 API Reference Guide - users Resource Data Parameters The PATCH supports a JSON body containing the following: Attribute name disabled systemrole Description A name for display in the UI but not for logging into the system. This is required. Status of the user. This is either false or true. This is optional. If you don't specify this value, this is set to false by default. This is the system role assigned directly to the user. This is optional. If you don't specify this value, this is set to Viewer by default. groupmembershipsan array describing each group the user belongs to. Each member of the array has an href and an id field. This is optional. All user are added to the Everyone group by default. type username password Where the user is defined. This can be either LOCAL to Platfora or from an EXTERNAL directory service. This is optional. If you don't specify this value, this is set to LOCAL by default. A unique name used to log into the Platfora application. This is required and must be unique. A password to log into the Platfora application. This is required. Sample Call Body For PATCH requests, you can include any of the valid user parameters. Use this call to update an single parameter or multiple parameters on a user instance. "data": "users": [ "username": "[email protected]" Success Response This response returns all users defined in Platfora: "data": "users": [ Page 24

25 API Reference Guide - users Resource "name": "Laura Higgins", "disabled": false, "systemrole": "Viewer", "groupmemberships": [ "href": " v1/groups/-1", "id": "-1" "effectiverole": "Viewer", "href": " users/ ", "id": " ", "type": "LOCAL", "username": "[email protected]" "_metadata":... "_links":... Page 25

26 Chapter 3 groups Resource Use the groups resource to manage Platfora groups. Topics: Overview List All groups GET a group POST a New group Update a group Overview The groups resource represents a permission group in Platfora. A group has an associated systemrole that grants permissions to its members. All Platfora users belong to the system defined Everyone group; You cannot update this group directly. Creating a new user does indirectly update the Everyone group by adding to its members. Platfora allows you to create groups locally in Platfora or reuse groups defined through an external directory service such as LDAP. Regardless of which technique you use, all groups have a defined system role. Groups can belong to other groups. A group's membership in other groups can change the group's effectiverole value. The effectiverole is the derived role for the group when taking into account the group's systemrole and its group membership. The most permissive role takes precedence. Once you create a local group, you cannot delete it. You can update local groups. The groups resource has the following structure: Attribute name description Description A name for display in the UI. A description for display in the UI. Page 26

27 API Reference Guide - groups Resource Attribute members href id type systemrole effectiverole Description An array describing each user that belongs to the group. A quick link to the group. The internal identifier for the group. Where the group is defined. This can be either LOCAL to Platfora or from an EXTERNAL directory service. This is the system role assigned directly to the group. The derived system role when taking into consideration the groups memberships in other groups. The most permissive role takes precedence. externalgroupid An ID from the external directory service. Not returned for LOCAL groups. externalgroupnamean name defined in the external directory service. Not returned for LOCAL groups. The members array returns a user structure for each member. That structure has the following content: Attribute href id type Description A link to the member's user resource. The user's id. Where the user originates. This can be either LOCAL to Platfora or from an EXTERNAL directory service. List All groups Use the GET method to list the groups currently configured in Platfora. URL /api/v1/groups HTTP Method GET Page 27

28 API Reference Guide - groups Resource Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call Body For GET requests, the body of the HTTP request should be empty. Success Response This response returns all groups defined in Platfora: "data": "groups": [ "name": "Anothergroup", "systemrole": "Analyst", "members": [ "effectiverole": "DataAdmin", "href": " groups/ ", "id": " ", "type": "LOCAL" "name": "Everyone", "description": "System everyone group", "members": [... "href": " groups/-1", "id": "-1", "type": "LOCAL" "name": "MaryLocalGroup", "description": "This is a local group I'm making for tests", "systemrole": "DataAdmin", "members": [ Page 28

29 API Reference Guide - groups Resource v1/groups/ ", v1/users/306537", "href": " "id": " ", "type": "GROUP" "href": " "id": "306537", "type": "USER" "href": " v1/users/434642", "id": "434642", "type": "USER" "effectiverole": "DataAdmin", "href": " groups/ ", "id": " ", "type": "LOCAL" "name": "Platfora Users", "systemrole": "UserAdmin", "externalgroupid": "381624", "externalgroupname": "Platfora Users", "effectiverole": "UserAdmin", "href": " groups/164", "id": "164", "type": "EXTERNAL" "_metadata":... "_links":... GET a group Use the GET method to retrieve a group configured in Platfora. Page 29

30 API Reference Guide - groups Resource URL /api/v1/groups/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call This method requires you to pass the group's id value. For GET requests, the body of the HTTP request should be empty. Success Response This response returns the group defined in Platfora: "data": "groups": [ "name": "MaryLocalGroup", "description": "This is a local group I'm making for tests", "systemrole": "DataAdmin", "members": [ "href": " v1/users/306537", "id": "306537", "type": "USER" "href": " v1/groups/ ", "id": " ", Page 30

31 API Reference Guide - groups Resource "type": "GROUP" "href": " v1/users/434642", "id": "434642", "type": "USER" "effectiverole": "DataAdmin", "href": " groups/ ", "id": " ", "type": "LOCAL" "_metadata":... "_links":... POST a New group Use the POST method to add a new group to Platfora. URL /api/v1/groups HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 31

32 API Reference Guide - groups Resource Data Parameters You pass this method a JSON body containing a required name parameter and zero or more optional parameters. Attribute name description members type systemrole externalgroupid externalgroupname Description A name for display in the UI. This is required. A description for display in the UI. This is optional. An array describing each user that belongs to the group. This is optional. Where the group is defined. This can be either LOCAL to Platfora or from an EXTERNAL directory service. This is optional. If you don't supply this value, LOCAL is assumed. This is the system role assigned directly to the group. This is optional. If you don't supply this value, the system uses the Viewer role. An ID from the external directory service. Required for EXTERNAL groups. An name defined in the external directory service. Required for EXTERNAL groups. Sample Call The following is an example of a JSON body you can pass to this call: "data": "groups": [ "name": "Lakers", "description": "This is a local group.", "systemrole": "DataAdmin" Success Response This response returns all groups defined in Platfora: "data": "groups": [ Page 32

33 API Reference Guide - groups Resource "name": "Lakers", "description": "This is a local group I'm making for tests", "systemrole": "DataAdmin", "members": [ "effectiverole": "DataAdmin", "href": " groups/ ", "id": " ", "type": "LOCAL" "_metadata":... "_links":... Update a group Use the PUT method to update currently configured in Platfora. URL /api/v1/groups/id HTTP Method PUT Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters This updates an existing group. You must pass in all the parameters. If you don't specify a parameter, the call sets the parameter to the default value. For example, if you pass a members array, you replace Page 33

34 API Reference Guide - groups Resource all the existing members with the members in your array. If the array is empty, then you remove all the members. Attribute name description members type systemrole externalgroupid externalgroupname Description A name for display in the UI. This is required. A description for display in the UI. This is optional. An array describing the group members. A member can be a user or a group. Where the group is defined. This can be either LOCAL to Platfora or from an EXTERNAL directory service. This is optional. If you don't supply this value, LOCAL is assumed. This is the system role assigned directly to the group. If you don't supply this value, the system uses the Viewer role. An ID from the external directory service. Required for EXTERNAL groups. An name defined in the external directory service. Required for EXTERNAL groups. For each member you must supply an id and a type value. The member has the following structure. "id": "33", "type": "GROUP" Sample Call The following is an example of a JSON body you can pass to this call: "data": "groups": [ "name": "HappyPeople", "description": "People who are happy", "systemrole": "DataAdmin", "members": [ "id": "434642", "type": "USER" "type": "LOCAL" Page 34

35 API Reference Guide - groups Resource Success Response This response returns all groups defined in Platfora: "data": "groups": [ "name": "HappyPeople", "description": "People who are happy", "systemrole": "DataAdmin", "members": [ "href": " v1/users/434642", "id": "434642", "type": "USER" "effectiverole": "DataAdmin", "href": " groups/ ", "id": " ", "type": "LOCAL" "_metadata":... "_links":... Page 35

36 Chapter 4 datasources Resource Use the datasources resource to create a data source or list data sources. Topics: Overview List All Data Sources List a Data Source Create a Data Source Overview A data source is a connection to a mount point or directory on an external data server, such as a file system or database server. You can use this resource to examine existing resources or create new ones. In addition to the common attributes, the datasources resource has the following attributes: Attribute sourcetype Description An enumerator which is one of DFS HIVE PLUGIN The PLUGIN data source represents a custom type. sourcedetails A structure defining the data source's properties. The sourcetype determines the content in the sourcedetails. The DFS and HIVE type are known to Platfora. The PLUGIN type is a custom type and its implementation defines the details. Specifying DFS Details The sourcedetails for a DFS source has this structure: "sourcetype": "DFS", Page 36

37 API Reference Guide - datasources Resource "sourcedetails": "path": "s3n://bucketname/path" The path parameter can take the following forms: Amazon S3 HDFS MapR s3n://bucketname/path hdfs://host:port/path maprfs://host:port/path Specifying HIVE Details The sourcedetails for a HIVE source has this structure: "sourcetype": "HIVE", "sourcedetails": "metastoreuri": thrift://n.n.n.n:port The metastoreuri is value is optional. List All Data Sources Lists the data sources currently configured in Platfora. This call returns an array of data source objects. URL /api/v1/datasources HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Page 37

38 API Reference Guide - datasources Resource Sample Call For GET requests, the body of the HTTP request should be empty. Success Response Returns all data sources defined in Platfora. The example below shows one of each type. HTTP status return code: 200 HTTP Body content: "_links":... "_metadata":... "data": "datasources": [ "datasets": [ "effectivepermissions": 63, "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:11:15.194Z", "user": "href": " users/7", "id": "7" "version": " F9" "href": " "id": "8", "name": "Copy of Uploads", "objectpermissions": "DataAccess": [ "memberid": 7, "type": "USER" "Owner": [ "memberid": 7, "type": "USER" Page 38

39 API Reference Guide - datasources Resource uploads" users/7", "sourcedetails": "path": "hdfs://myhdfsserver.com:8020/user/platfora/ "sourcetype": "DFS", "version": " F9" "datasets": [ "effectivepermissions": 63, "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:09:40.379Z", "user": "href": " "id": "7" "version": " F6" "href": " "id": "7", "name": "Hive Default Data Source from configs", "objectpermissions": "DataAccess": [ "memberid": 7, "type": "USER" "Owner": [ "memberid": 7, "type": "USER" "sourcedetails": "sourcetype": "HIVE", "version": " F6" "datasets": [ "effectivepermissions": 63, "history": [ "lifecyclestage": "created", "replaces": null, Page 39

40 API Reference Guide - datasources Resource users/7", "time": " T22:09:28.272Z", "user": "href": " "id": "7" "version": " F4" "href": " "id": "5", "name": "Hive QA MapR", "objectpermissions": "DataAccess": [ "memberid": 7, "type": "USER" "Owner": [ "memberid": 7, "type": "USER" "sourcedetails": "metastoreuri": "thrift://qamapr-1.example.com:9999/" "sourcetype": "HIVE", "version": " F4" "datasets": [ "effectivepermissions": 63, "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:09:23.253Z", "user": "href": " users/7", "id": "7" "version": " F3" "href": " "id": "4", "name": "QA EMR", "objectpermissions": Page 40

41 API Reference Guide - datasources Resource users/7", "DataAccess": [ "memberid": 7, "type": "USER" "Owner": [ "memberid": 7, "type": "USER" "sourcedetails": "path": "s3n://platfora.qa/" "sourcetype": "DFS", "version": " F3" "datasets": [ "effectivepermissions": 63, "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:09:35.664Z", "user": "href": " "id": "7" "version": " F5" "href": " "id": "6", "name": "QA MapR", "objectpermissions": "DataAccess": [ "memberid": 7, "type": "USER" "Owner": [ "memberid": 7, "type": "USER" "sourcedetails": Page 41

42 API Reference Guide - datasources Resource datasets/1", datasets/2", users/-1", "path": "maprfs:///mapr/qa_mapr_cluster/" "sourcetype": "DFS", "version": " F5" "datasets": [ "href": " "id": "1", "name": "Date" "href": " "id": "2", "name": "Time" "effectivepermissions": 38, "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:06:34.765Z", "user": "href": " "id": "-1" "version": " " "href": " "id": "1", "name": "System", "objectpermissions": "Create": [ "memberid": -1, "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": -1, Page 42

43 API Reference Guide - datasources Resource system" datasets/3", datasets/4", datasets/5", users/-1", "type": "USER" "sourcedetails": "path": "hdfs://myhdfsserver.com:8020/user/platfora/ "sourcetype": "DFS", "version": " " "datasets": [ "href": " "id": "3", "name": "Airports" "href": " "id": "4", "name": "Flights" "href": " "id": "5", "name": "US Pop by State" "effectivepermissions": 38, "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:06:35.391Z", "user": "href": " "id": "-1" "version": " " "href": " "id": "2", "name": "Uploads", "objectpermissions": "Create": [ "memberid": -1, Page 43

44 API Reference Guide - datasources Resource uploads" "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": -1, "type": "USER" "sourcedetails": "path": "hdfs://myhdfsserver.com:8020/user/platfora/ "sourcetype": "DFS", "version": " " List a Data Source Use the GET method to list a specific data source. URL /api/v1/datasources/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 44

45 API Reference Guide - datasources Resource Data Parameters None. Sample Call For GET requests, the Body of the HTTP request should be empty. Success Response Returns the data source with the ID given in the URL. Create a Data Source Creates a single data source of any type. This call creates a single data source. You can only create one data source at a time. This restriction allows Platfora to return a different HTTP response code for each data source. You can create a DFS or HIVE resource with this call. DFS is used with HDFS, Simple Storage Service (S3) and MapR sources. Platfora sets the authenticated caller as the data source owner and grants the caller data access. The Platfora server also assigns an ID to the data source. A successful return body includes the ID. URL /api/v1/datasources HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 45

46 API Reference Guide - datasources Resource Data Parameters The caller must supply a unique name. In addition, this call requires the following parameters: Attribute sourcetype Description An enumerator which is one of DFS HIVE PLUGIN The PLUGIN data source represents a custom type. sourcedetails A structure defining the data source's properties. The sourcetype determines the content in the sourcedetails. The DFS and HIVE type are known to Platfora. The PLUGIN type is a custom type and its implementation defines the details. Sample Calls This sample POST body creates an HDFS data source. The Platfora server assigns an ID value to the data source as it creates the data source. The following illustrates a sample POST body for a DFS data source: "data": "datasources": [ "name": "string", "sourcetype": "DFS", "sourcedetails": "path": "s3n://ourdata.store/" This sample POST body creates a Hive Thrift Metastore data source. "data": "datasources": [ "name": "Hive QA MapR", "sourcedetails": "csvpath": "bigfile.csv" "metastoreuri": "thrift://qamapr-1.example.com:9999/" Page 46

47 API Reference Guide - datasources Resource "sourcetype": "HIVE" This sample POST body creates a Hive RDBMS Metastore connection data source. "data": "datasources": [ "name": "Hive Default Data Source from configs", "sourcedetails": "sourcetype": "HIVE" Success Response The JSON response body below is returned when an HDFS data source is created. "_links":... "_metadata":... "data": "datasources": [ "datasets": [ "history": [ "lifecyclestage": "created", "replaces": null, "time": " T00:20:37.768Z", "user": "href": " users/7", "id": "7" "version": " FE4" "href": " "id": "9", Page 47

48 API Reference Guide - datasources Resource "name": "QA CDH Dumbo", "objectpermissions": "DataAccess": [ "memberid": 7, "type": "USER" "Owner": [ "memberid": 7, "type": "USER" "sourcedetails": "path": "hdfs://dumbo1.example.com:8020/" "sourcetype": "DFS", "version": " FE4" Page 48

49 Chapter 5 datasets Resource Use the datasets resource to list datasets or create a new dataset. Topics: Overview List All Datasets List a Dataset Create Datasets Overview A dataset is a metadata description of how data is structured. If you are familiar with extract, transformation, and load (ETL) workflows, a dataset makes up the extract and transformation logic in Platfora. Dataset Attributes A dataset describes the rows and columns, the base fields and their associated data types, computed dimension fields, measures derived from quantitative data fields, and references (or joins) to other related datasets. The following table summarizes the resource attributes. Attribute abbreviation deprecated datasource adapter fields key Description Specifies name of the referenced source file in Hadoop. For internal system use only. This field is currently not used or respected. Specifies the datasets' source. Specifies the origination of the An array of field resources. Contains the dataset key. A key is single field (or combination of fields) that uniquely identifies a dataset row. A key is similar to a primary key in a relational database. Page 49

50 API Reference Guide - datasets Resource Attribute history href Description Summarizes the datasets change history. Contains the link to the resource. List All Datasets Use the GET method to retrieve and list the datasets currently configured in Platfora. URL /api/v1/datasets HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all datasets defined in Platfora. In this example, it includes the Platfora Date and Time datasets. HTTP status return code: 200 HTTP Body content: "_links":... Page 50

51 API Reference Guide - datasets Resource "_metadata":... "data": "datasets": [ "abbreviation": "Airports", "adapter": "adapterdetails": "hasheader": "true", "nullstring": "\\N", "path": "airports.csv", "separatorchar": "," "adaptertype": "CSV" "datasource": "href": " "id": "2", "name": "Uploads" "description": "Domestic airport name and location information", "effectivepermissions": 63, "fields": [ "abbreviation": "Code", "description": "international aviation transportation association 3 digit airport code", "id": "32", "includeoriginalvalue": true, "kind": "BASE", "name": "Code", "role": "VALUE", "type": "STRING", "version": " C" "abbreviation": "Name", "description": "the name of the airport", "id": "33", "includeoriginalvalue": true, "kind": "BASE", "name": "Name", "role": "VALUE", "type": "STRING", "version": " D" Page 51

52 API Reference Guide - datasets Resource "abbreviation": "Country", "description": "the country of the airport", "id": "34", "includeoriginalvalue": true, "kind": "BASE", "name": "Country", "role": "VALUE", "type": "STRING", "version": " E" "abbreviation": "State", "description": "the state of the airport", "id": "35", "includeoriginalvalue": true, "kind": "BASE", "name": "State", "role": "VALUE", "type": "STRING", "version": " F" "abbreviation": "City", "description": "the city of the airport", "id": "36", "includeoriginalvalue": true, "kind": "BASE", "name": "City", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "lat", "description": "latitude of the airport", "hidden": true, "id": "37", "includeoriginalvalue": true, "kind": "BASE", "name": "lat", Page 52

53 API Reference Guide - datasets Resource "role": "VALUE", "type": "DOUBLE", "version": " " "abbreviation": "Latitude", "dependencies": [ "path": [ "id": "37", "name": "lat", "version": " " "description": "latitude of the airport rounded to ten thousandth of a degree", "expression": "ROUND(lat, 4)", "id": "38", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "Latitude", "role": "VALUE", "type": "DOUBLE", "version": " " "abbreviation": "long", "description": "longitude of the airport", "hidden": true, "id": "39", "includeoriginalvalue": true, "kind": "BASE", "name": "long", "role": "VALUE", "type": "DOUBLE", "version": " " "abbreviation": "Longitude", "dependencies": [ "path": [ "id": "39", Page 53

54 API Reference Guide - datasets Resource "name": "long", "version": " " "description": "longitude of the airport rounded to ten thousandth of a degree", "expression": "ROUND(long, 4)", "id": "40", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "Longitude", "role": "VALUE", "type": "DOUBLE", "version": " " "abbreviation": "local_utc_time", "description": "the local timezone expressed in universal time code", "hidden": true, "id": "41", "includeoriginalvalue": true, "kind": "BASE", "name": "local_utc_time", "role": "VALUE", "type": "INTEGER", "version": " " "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:07:49.862Z", "user": "href": " "id": "7" "version": " B" "href": " "id": "3", "key": [ "abbreviation": "Code", Page 54

55 API Reference Guide - datasets Resource "description": "international aviation transportation association 3 digit airport code", "id": "32", "includeoriginalvalue": true, "kind": "BASE", "name": "Code", "role": "VALUE", "type": "STRING", "version": " C" "name": "Airports", "objectpermissions": "Create": [ "memberid": -1, "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": 7, "type": "USER" "memberid": 5094, "type": "USER" "version": " B" "abbreviation": "Date", "adapter": "adapterdetails": "encoding": "UTF-8", "escapechar": "\\", "hasheader": false, "maxlinelength": , "path": "date.csv", "quotechar": "\"", "recordseparator": "\n", "separatorchar": ",", "skiplines": 0 Page 55

56 API Reference Guide - datasets Resource "adaptertype": "CSV" "datasource": "href": " "id": "1", "name": "System" "description": "A basic calendar provided by Platfora.", "effectivepermissions": 38, "fields": [ "abbreviation": "Date", "description": "A single day, expressed as a date-valued column ( ).", "id": "1", "includeoriginalvalue": true, "kind": "BASE", "name": "Date", "role": "VALUE", "type": "DATETIME", "version": " " "abbreviation": "Month", "description": "A calendar month (for example, Jan 2012)", "id": "2", "includeoriginalvalue": true, "kind": "BASE", "name": "Month", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Quarter", "description": "A calendar quarter (for example, Q1 2012)", "id": "3", "includeoriginalvalue": true, "kind": "BASE", "name": "Quarter", "role": "VALUE", "type": "STRING", Page 56

57 API Reference Guide - datasets Resource "version": " " "abbreviation": "Weekday", "description": "Day in week (for example, Sunday=1, Saturday=7)", "id": "4", "includeoriginalvalue": true, "kind": "BASE", "name": "Weekday_Number", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "Weekday", "description": "A day of the week (for example, Saturday)", "id": "5", "includeoriginalvalue": true, "kind": "BASE", "name": "Weekday", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Month Num", "description": "Month number in the year (for example, January=1)", "id": "6", "includeoriginalvalue": true, "kind": "BASE", "name": "Month_Number", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "Month", "description": "A month of the year (for example, January)", "id": "7", Page 57

58 API Reference Guide - datasets Resource "includeoriginalvalue": true, "kind": "BASE", "name": "Month_Name", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Quarter", "description": "A calendar quarter without the year included (for example, Q1)", "id": "8", "includeoriginalvalue": true, "kind": "BASE", "name": "Quarter_Name", "role": "VALUE", "type": "STRING", "version": " A" "abbreviation": "Weekend?", "description": "One of the values \"Weekend\" or \"Weekday \". \"Weekend\" is used for Saturday and Sunday", "id": "9", "includeoriginalvalue": true, "kind": "BASE", "name": "Work_Day", "role": "VALUE", "type": "STRING", "version": " B" "abbreviation": "Year", "description": "A calendar year (for example, 2012)", "id": "10", "includeoriginalvalue": true, "kind": "BASE", "name": "Year", "role": "VALUE", "type": "INTEGER", "version": " C" "abbreviation": "Day", Page 58

59 API Reference Guide - datasets Resource "description": "A day of the month (for example, 31 for January 31st)", "id": "11", "includeoriginalvalue": true, "kind": "BASE", "name": "Day_of_Month", "role": "VALUE", "type": "INTEGER", "version": " D" "abbreviation": "Week", "description": "The week number within the year", "id": "12", "includeoriginalvalue": true, "kind": "BASE", "name": "Week", "role": "VALUE", "type": "STRING", "version": " E" "abbreviation": "Day", "description": "The day number within the year", "id": "13", "includeoriginalvalue": true, "kind": "BASE", "name": "Day_of_Year", "role": "VALUE", "type": "INTEGER", "version": " F" "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:06:39.334Z", "user": "href": " "id": "-1" "version": " " Page 59

60 API Reference Guide - datasets Resource "href": " "id": "1", "key": [ "abbreviation": "Date", "description": "A single day, expressed as a date-valued column ( ).", "id": "1", "includeoriginalvalue": true, "kind": "BASE", "name": "Date", "role": "VALUE", "type": "DATETIME", "version": " " "name": "Date", "objectpermissions": "Create": [ "memberid": -1, "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": -1, "type": "USER" "version": " " "abbreviation": "Flights", "adapter": "adapterdetails": "hasheader": "true", "nullstring": "\\N", "path": "flights.csv", "separatorchar": "," "adaptertype": "CSV" Page 60

61 API Reference Guide - datasets Resource "datasource": "href": " "id": "2", "name": "Uploads" "description": "Domestic FAA flight records from October 2012, the month of Hurricane Sandy", "effectivepermissions": 63, "fields": [ "abbreviation": "year", "description": "year of flight departure", "hidden": true, "id": "42", "includeoriginalvalue": true, "kind": "BASE", "name": "year", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "month", "description": "month 1-12 of flight departure", "hidden": true, "id": "43", "includeoriginalvalue": true, "kind": "BASE", "name": "month", "role": "VALUE", "type": "STRING", "version": " A" "abbreviation": "day", "description": "day 1-31 of flight departure", "hidden": true, "id": "44", "includeoriginalvalue": true, "kind": "BASE", "name": "day", "role": "VALUE", "type": "STRING", "version": " B" Page 61

62 API Reference Guide - datasets Resource "abbreviation": "Carrier Code", "description": "the IATA carrier code", "id": "45", "includeoriginalvalue": true, "kind": "BASE", "name": "Carrier Code", "role": "VALUE", "type": "STRING", "version": " C" "abbreviation": "Tail Number", "description": "the tail number of the aircraft", "id": "46", "includeoriginalvalue": true, "kind": "BASE", "name": "Tail Number", "role": "VALUE", "type": "STRING", "version": " D" "abbreviation": "Flight Number", "description": "the flight number", "id": "47", "includeoriginalvalue": true, "kind": "BASE", "name": "Flight Number", "role": "VALUE", "type": "INTEGER", "version": " E" "abbreviation": "orig_airport", "description": "the code of the origin airport where a flight departed", "hidden": true, "id": "48", "includeoriginalvalue": true, "kind": "BASE", "name": "orig_airport", Page 62

63 API Reference Guide - datasets Resource "role": "VALUE", "type": "STRING", "version": " F" "abbreviation": "dest_airport", "description": "the code of the destination airport where a flight arrived", "hidden": true, "id": "49", "includeoriginalvalue": true, "kind": "BASE", "name": "dest_airport", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "crs_depart_time", "description": "local departure time of flight as in the computer reservation system", "hidden": true, "id": "50", "includeoriginalvalue": true, "kind": "BASE", "name": "crs_depart_time", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "depart_time", "description": "local departure time of a flight that took off", "hidden": true, "id": "51", "includeoriginalvalue": true, "kind": "BASE", "name": "depart_time", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "departure_delay", Page 63

64 API Reference Guide - datasets Resource "description": "the difference between scheduled and actual departure in minutes", "hidden": true, "id": "52", "includeoriginalvalue": true, "kind": "BASE", "name": "departure_delay", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "taxi_out_mins", "description": "taxi time in minutes spent on the runway at the departure airport", "hidden": true, "id": "53", "includeoriginalvalue": true, "kind": "BASE", "name": "taxi_out_mins", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "taxi_in_mins", "description": "taxi time in minutes spent on the runway at the arrival airport", "hidden": true, "id": "54", "includeoriginalvalue": true, "kind": "BASE", "name": "taxi_in_mins", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "crs_arrive_time", "description": "local arrival time of a flight as in the computer reservation system", "hidden": true, "id": "55", "includeoriginalvalue": true, "kind": "BASE", "name": "crs_arrive_time", "role": "VALUE", Page 64

65 API Reference Guide - datasets Resource "type": "STRING", "version": " " "abbreviation": "arrive_time", "description": "local arrival time of a flight that landed", "hidden": true, "id": "56", "includeoriginalvalue": true, "kind": "BASE", "name": "arrive_time", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "arrival_delay", "description": "the difference between scheduled and actual arrival time in minutes", "hidden": true, "id": "57", "includeoriginalvalue": true, "kind": "BASE", "name": "arrival_delay", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "cancel_boolean", "description": "1 if flight was cancelled, 0 if it was not cancelled", "hidden": true, "id": "58", "includeoriginalvalue": true, "kind": "BASE", "name": "cancel_boolean", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "cancel_code", "description": "cancel reason (A = carrier, B = weather, C = national airspace system, D = security)", Page 65

66 API Reference Guide - datasets Resource "hidden": true, "id": "59", "includeoriginalvalue": true, "kind": "BASE", "name": "cancel_code", "role": "VALUE", "type": "STRING", "version": " A" "abbreviation": "diverted_boolean", "description": "1 if flight was diverted, 0 if it was not diverted", "hidden": true, "id": "60", "includeoriginalvalue": true, "kind": "BASE", "name": "diverted_boolean", "role": "VALUE", "type": "INTEGER", "version": " B" "abbreviation": "Estimated Duration", "description": "the total estimated duration of a flight in minutes from the computer reservation system", "id": "61", "includeoriginalvalue": false, "kind": "BASE", "name": "Estimated Duration", "quickfieldmeasures": [ "Avg", "Sum" "role": "VALUE", "type": "INTEGER", "version": " C" "abbreviation": "Flight Duration", "description": "the total actual duration in minutes of a flight", "id": "62", "includeoriginalvalue": false, "kind": "BASE", Page 66

67 API Reference Guide - datasets Resource "name": "Flight Duration", "quickfieldmeasures": [ "Avg", "Sum" "role": "VALUE", "type": "INTEGER", "version": " D" "abbreviation": "Airtime", "description": "the time in the air in minutes of a flight", "id": "63", "includeoriginalvalue": false, "kind": "BASE", "name": "Airtime", "quickfieldmeasures": [ "Avg", "Sum" "role": "VALUE", "type": "INTEGER", "version": " E" "abbreviation": "Distance", "description": "the distance traveled in miles", "id": "64", "includeoriginalvalue": false, "kind": "BASE", "name": "Distance", "quickfieldmeasures": [ "Avg", "Sum" "role": "VALUE", "type": "INTEGER", "version": " F" "abbreviation": "Departure Airport", "description": "the airport of origin for a flight - joins to the Airports dataset", "id": "65", Page 67

68 API Reference Guide - datasets Resource "kind": "REFERENCE", "name": "Departure Airport", "role": "REFERENCE", "target": "datasetid": "3", "datasetname": "Airports", "datasetversion": " B", "foreignkey": [ "id": "48", "name": "orig_airport" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Arrival Airport", "description": "the arrival airport of a flight - joins to the Airports dataset", "id": "66", "kind": "REFERENCE", "name": "Arrival Airport", "role": "REFERENCE", "target": "datasetid": "3", "datasetname": "Airports", "datasetversion": " B", "foreignkey": [ "id": "49", "name": "dest_airport" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Departure Date", "description": "the departure date of a flight - joins to Date dataset", "id": "67", "kind": "REFERENCE", Page 68

69 API Reference Guide - datasets Resource "name": "Departure Date", "role": "REFERENCE", "target": "datasetid": "1", "datasetname": "Date", "datasetversion": " ", "foreignkey": [ "id": "75", "name": "depart_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Departure Time", "description": "the departure time of a flight - joins to Time dataset", "id": "68", "kind": "REFERENCE", "name": "Departure Time", "role": "REFERENCE", "target": "datasetid": "2", "datasetname": "Time", "datasetversion": " ", "foreignkey": [ "id": "75", "name": "depart_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Scheduled Departure Date", "description": "the scheduled departure date of a flight in the computer system- joins to Date dataset", "id": "69", "kind": "REFERENCE", "name": "Scheduled Departure Date", Page 69

70 API Reference Guide - datasets Resource "role": "REFERENCE", "target": "datasetid": "1", "datasetname": "Date", "datasetversion": " ", "foreignkey": [ "id": "76", "name": "crs_depart_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Scheduled Departure Time", "description": "the scheduled departure time of a flight in the computer system - joins to Time dataset", "id": "70", "kind": "REFERENCE", "name": "Scheduled Departure Time", "role": "REFERENCE", "target": "datasetid": "2", "datasetname": "Time", "datasetversion": " ", "foreignkey": [ "id": "76", "name": "crs_depart_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Scheduled Arrival Time", "description": "the scheduled local arrival time of a flight in the computer system - joins to Time dataset", "id": "71", "kind": "REFERENCE", "name": "Scheduled Arrival Time", "role": "REFERENCE", Page 70

71 API Reference Guide - datasets Resource "target": "datasetid": "2", "datasetname": "Time", "datasetversion": " ", "foreignkey": [ "id": "78", "name": "crs_arrive_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Scheduled Arrival Date", "description": "Do not use - Arrival Date is NULL in this data", "hidden": true, "id": "72", "kind": "REFERENCE", "name": "Scheduled Arrival Date", "role": "REFERENCE", "target": "datasetid": "1", "datasetname": "Date", "datasetversion": " ", "foreignkey": [ "id": "78", "name": "crs_arrive_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Arrival Time", "description": "the actual local arrival time of a flight - joins to Time dataset", "id": "73", "kind": "REFERENCE", "name": "Arrival Time", "role": "REFERENCE", "target": Page 71

72 API Reference Guide - datasets Resource data", "datasetid": "2", "datasetname": "Time", "datasetversion": " ", "foreignkey": [ "id": "77", "name": "arrive_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "Arrival Date", "description": "Do not use - Arrival Date is NULL in this "hidden": true, "id": "74", "kind": "REFERENCE", "name": "Arrival Date", "role": "REFERENCE", "target": "datasetid": "1", "datasetname": "Date", "datasetversion": " ", "foreignkey": [ "id": "77", "name": "arrive_datetime" "href": " "type": "REFERENCE", "version": " " "abbreviation": "depart_datetime", "dependencies": [ "path": [ "id": "51", "name": "depart_time", "version": " " Page 72

73 API Reference Guide - datasets Resource "path": [ "id": "44", "name": "day", "version": " B" "path": [ "id": "42", "name": "year", "version": " " "path": [ "id": "43", "name": "month", "version": " A" "description": "date and local time of departure", "expression": "TO_DATE(CONCAT(month,\"/\",day,\"/\",year, \":\",REGEX_REPLACE(depart_time,\"\\b(\\d3)\\b\",\"0$1\")),\"MM/dd/ yyyy:hhmm\")", "hidden": true, "id": "75", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "depart_datetime", "role": "VALUE", "type": "DATETIME", "version": " A" "abbreviation": "crs_depart_datetime", "dependencies": [ "path": [ "id": "43", "name": "month", "version": " A" Page 73

74 API Reference Guide - datasets Resource "path": [ "id": "44", "name": "day", "version": " B" "path": [ "id": "50", "name": "crs_depart_time", "version": " " "path": [ "id": "42", "name": "year", "version": " " "description": "scheduled date and time of departure as in the computer reservation system", "expression": "TO_DATE(CONCAT(month,\"/\",day,\"/\",year,\": \",REGEX_REPLACE(crs_depart_time,\"\\b(\\d3)\\b\",\"0$1\")),\"MM/dd/ yyyy:hhmm\")", "hidden": true, "id": "76", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "crs_depart_datetime", "role": "VALUE", "type": "DATETIME", "version": " B" "abbreviation": "arrive_datetime", "dependencies": [ "path": [ "id": "56", Page 74

75 API Reference Guide - datasets Resource "name": "arrive_time", "version": " " "description": "local time of arrival (has time only because sometimes a flight arrives on a different date than its departure)", "expression": "TO_DATE(REGEX_REPLACE(arrive_time,\"\\b(\ \d3)\\b\",\"0$1\"),\"hhmm\")", "hidden": true, "id": "77", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "arrive_datetime", "role": "VALUE", "type": "DATETIME", "version": " C" "abbreviation": "crs_arrive_datetime", "dependencies": [ "path": [ "id": "55", "name": "crs_arrive_time", "version": " " "description": "scheduled local time of arrival in computer reservation system", "expression": "TO_DATE(REGEX_REPLACE(crs_arrive_time,\"\\b(\ \d3)\\b\",\"0$1\"),\"hhmm\")", "hidden": true, "id": "78", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "crs_arrive_datetime", "role": "VALUE", "type": "DATETIME", "version": " D" "abbreviation": "Cancel Status", "dependencies": [ Page 75

76 API Reference Guide - datasets Resource "path": [ "id": "58", "name": "cancel_boolean", "version": " " "description": "denotes if a flight was cancelled or not cancelled", "expression": "CASE WHEN cancel_boolean=0 THEN \"Not Cancelled\" WHEN cancel_boolean=1 THEN \"Cancelled\" ELSE NULL END", "id": "79", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "Cancel Status", "role": "VALUE", "type": "STRING", "version": " E" "abbreviation": "Cancel Reason", "dependencies": [ "path": [ "id": "59", "name": "cancel_code", "version": " A" "description": "if a flight was cancelled, denotes the reason for the cancellation", "expression": "CASE WHEN cancel_code=\"a\" THEN \"Carrier \" WHEN cancel_code=\"b\" THEN \"Weather\" WHEN cancel_code=\"c\" THEN \"National Airspace System\" WHEN cancel_code=\"d\" THEN \"Security\" ELSE \"Not Applicable\" END", "id": "80", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "Cancel Reason", "role": "VALUE", "type": "STRING", "version": " F" Page 76

77 API Reference Guide - datasets Resource "abbreviation": "Diverted Status", "dependencies": [ "path": [ "id": "60", "name": "diverted_boolean", "version": " B" "description": "denotes if a flight was diverted from its original destination or not diverted", "expression": "CASE WHEN diverted_boolean=0 THEN \"Not Diverted\" WHEN diverted_boolean=1 THEN \"Diverted\" ELSE NULL END", "id": "81", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "Diverted Status", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Flight Records (COUNT)", "dependencies": [ "description": "number of rows in the flight dataset", "expression": "COUNT()", "id": "82", "kind": "MEASURE", "name": "Flight Records (COUNT)", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "Arrival Delay (AVG)", "dependencies": [ "path": [ "id": "57", "name": "arrival_delay", "version": " " Page 77

78 API Reference Guide - datasets Resource "description": "the average arrival delay in minutes. early flights are negative values.", "expression": "AVG(arrival_delay)", "id": "83", "kind": "MEASURE", "name": "Arrival Delay (AVG)", "role": "MEASURE", "type": "DOUBLE", "version": " " "abbreviation": "Departure Delay (AVG)", "dependencies": [ "path": [ "id": "52", "name": "departure_delay", "version": " " "description": "the average departure delay in minutes. early flights are negative values.", "expression": "AVG(departure_delay)", "id": "84", "kind": "MEASURE", "name": "Departure Delay (AVG)", "role": "MEASURE", "type": "DOUBLE", "version": " " "abbreviation": "Arrival Delay (MAX)", "dependencies": [ "path": [ "id": "57", "name": "arrival_delay", "version": " " Page 78

79 API Reference Guide - datasets Resource "description": "the longest arrival delay in minutes", "expression": "MAX(arrival_delay)", "id": "85", "kind": "MEASURE", "name": "Arrival Delay (MAX)", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "Departure Delay (MAX)", "dependencies": [ "path": [ "id": "52", "name": "departure_delay", "version": " " "description": "the longest departure delay in minutes", "expression": "MAX(departure_delay)", "id": "86", "kind": "MEASURE", "name": "Departure Delay (MAX)", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "Taxi on Departure (MAX)", "dependencies": [ "path": [ "id": "53", "name": "taxi_out_mins", "version": " " Page 79

80 API Reference Guide - datasets Resource "description": "the maximum taxi time in minutes at the departure airport", "expression": "MAX(taxi_out_mins)", "id": "87", "kind": "MEASURE", "name": "Taxi on Departure (MAX)", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "Taxi on Departure (AVG)", "dependencies": [ "path": [ "id": "53", "name": "taxi_out_mins", "version": " " "description": "the average taxi time in minutes at the departure airport", "expression": "AVG(taxi_out_mins)", "id": "88", "kind": "MEASURE", "name": "Taxi on Departure (AVG)", "role": "MEASURE", "type": "DOUBLE", "version": " " "abbreviation": "Taxi on Arrival (MAX)", "dependencies": [ "path": [ "id": "54", "name": "taxi_in_mins", "version": " " Page 80

81 API Reference Guide - datasets Resource "description": "the maximum taxi time in minutes at the arrival airport", "expression": "MAX(taxi_in_mins)", "id": "89", "kind": "MEASURE", "name": "Taxi on Arrival (MAX)", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "Taxi on Arrival (AVG)", "dependencies": [ "path": [ "id": "54", "name": "taxi_in_mins", "version": " " "description": "the average taxi time in minutes at the arrival airport", "expression": "AVG(taxi_in_mins)", "id": "90", "kind": "MEASURE", "name": "Taxi on Arrival (AVG)", "role": "MEASURE", "type": "DOUBLE", "version": " " "abbreviation": "Planes (DISTINCT)", "dependencies": [ "path": [ "id": "46", "name": "Tail Number", "version": " D" Page 81

82 API Reference Guide - datasets Resource "description": "the number of distinct aircraft in the data", "expression": "DISTINCT([Tail Number)", "id": "91", "kind": "MEASURE", "name": "Planes (DISTINCT)", "role": "MEASURE", "type": "LONG", "version": " A" "abbreviation": "Carriers (DISTINCT)", "dependencies": [ "path": [ "id": "45", "name": "Carrier Code", "version": " C" "description": "the number of distinct airline carriers in the data", "expression": "DISTINCT([Carrier Code)", "id": "92", "kind": "MEASURE", "name": "Carriers (DISTINCT)", "role": "MEASURE", "type": "LONG", "version": " B" "abbreviation": "Destinations (DISTINCT)", "dependencies": [ "path": [ "id": "49", "name": "dest_airport", "version": " " Page 82

83 API Reference Guide - datasets Resource "description": "the number of distinct arrival airports in the data", "expression": "DISTINCT(dest_airport)", "id": "93", "kind": "MEASURE", "name": "Destinations (DISTINCT)", "role": "MEASURE", "type": "LONG", "version": " C" "abbreviation": "Origins (DISTINCT)", "dependencies": [ "path": [ "id": "48", "name": "orig_airport", "version": " F" "description": "the number of distinct departure airports in the data", "expression": "DISTINCT(orig_airport)", "id": "94", "kind": "MEASURE", "name": "Origins (DISTINCT)", "role": "MEASURE", "type": "LONG", "version": " D" "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:07:53.920Z", "user": "href": " "id": "7" "version": " " "href": " "id": "4", "key": [ Page 83

84 API Reference Guide - datasets Resource "name": "Flights", "objectpermissions": "Create": [ "memberid": -1, "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": 7, "type": "USER" "memberid": 5094, "type": "USER" "version": " " "abbreviation": "Time", "adapter": "adapterdetails": "encoding": "UTF-8", "escapechar": "\\", "hasheader": false, "maxlinelength": , "path": "time.csv", "quotechar": "\"", "recordseparator": "\n", "separatorchar": ",", "skiplines": 0 "adaptertype": "CSV" "datasource": "href": " "id": "1", "name": "System" "description": "Default time dataset with one second resolution.", "effectivepermissions": 38, "fields": [ Page 84

85 API Reference Guide - datasets Resource "abbreviation": "Second of Day", "description": "Number of seconds into a single day", "id": "14", "includeoriginalvalue": true, "kind": "BASE", "name": "Second of Day", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "Time in Seconds", "description": "Time of day with 1-second resolution", "id": "15", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in Seconds", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Time in 5 Seconds", "description": "Time of day with 5-second resolution", "id": "16", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 5 Seconds", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Time in 10 Seconds", "description": "Time of day with 10-second resolution", "id": "17", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 10 Seconds", "role": "VALUE", Page 85

86 API Reference Guide - datasets Resource "type": "STRING", "version": " " "abbreviation": "Time in 15 Seconds", "description": "Time of day with 15-second resolution", "id": "18", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 15 Seconds", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Time in 30 Seconds", "description": "Time of day with 30-second resolution", "id": "19", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 30 Seconds", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Time in Minutes", "description": "Time of day with 1-minute resolution", "id": "20", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in Minutes", "role": "VALUE", "type": "STRING", "version": " A" "abbreviation": "Time in 5 Minutes", "description": "Time of day with 5-minute resolution", "id": "21", "includeoriginalvalue": true, Page 86

87 API Reference Guide - datasets Resource "kind": "BASE", "name": "Time in 5 Minutes", "role": "VALUE", "type": "STRING", "version": " B" "abbreviation": "Time in 10 Minutes", "description": "Time of day with 10-minute resolution", "id": "22", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 10 Minutes", "role": "VALUE", "type": "STRING", "version": " C" "abbreviation": "Time in 15 Minutes", "description": "Time of day with 15-minute resolution", "id": "23", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 15 Minutes", "role": "VALUE", "type": "STRING", "version": " D" "abbreviation": "Time in 30 Minutes", "description": "Time of day with 30-minute resolution", "id": "24", "includeoriginalvalue": true, "kind": "BASE", "name": "Time in 30 Minutes", "role": "VALUE", "type": "STRING", "version": " E" "abbreviation": "Hour", "description": "Hour of day", Page 87

88 API Reference Guide - datasets Resource "id": "25", "includeoriginalvalue": true, "kind": "BASE", "name": "Hour", "role": "VALUE", "type": "STRING", "version": " F" "abbreviation": "Hour by 2", "description": "Hour of day with 2-hour resolution", "id": "26", "includeoriginalvalue": true, "kind": "BASE", "name": "Hour by 2", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Hour by 3", "description": "Hour of day with 3-hour resolution", "id": "27", "includeoriginalvalue": true, "kind": "BASE", "name": "Hour by 3", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Hour by 4", "description": "Hour of day with 4-hour resolution", "id": "28", "includeoriginalvalue": true, "kind": "BASE", "name": "Hour by 4", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Hour by 6", Page 88

89 API Reference Guide - datasets Resource "description": "Hour of day with 6-hour resolution", "id": "29", "includeoriginalvalue": true, "kind": "BASE", "name": "Hour by 6", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "Hour by 8", "description": "Hour of day with 8-hour resolution", "id": "30", "includeoriginalvalue": true, "kind": "BASE", "name": "Hour by 8", "role": "VALUE", "type": "STRING", "version": " " "abbreviation": "AM/PM", "description": "AM = morning or PM = afternoon", "id": "31", "includeoriginalvalue": true, "kind": "BASE", "name": "AM/PM", "role": "VALUE", "type": "STRING", "version": " " "history": [ "lifecyclestage": "created", "replaces": null, "time": " T22:06:42.242Z", "user": "href": " "id": "-1" "version": " " Page 89

90 API Reference Guide - datasets Resource "href": " "id": "2", "key": [ "abbreviation": "Second of Day", "description": "Number of seconds into a single day", "id": "14", "includeoriginalvalue": true, "kind": "BASE", "name": "Second of Day", "role": "VALUE", "type": "INTEGER", "version": " " "name": "Time", "objectpermissions": "Create": [ "memberid": -1, "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": -1, "type": "USER" "version": " " "abbreviation": "US_population_by_state", "adapter": "adapterdetails": "delimdefinition": [ "encoding": "UTF-8", "escapechar": "\\", "filter": "", "hasheader": true, "islinebased": false, "maxlinelength": , "parsertype": "TEXT", Page 90

91 API Reference Guide - datasets Resource "path": "US_population_by_state.csv", "quotechar": "\"", "recordseparator": null, "regex": "", "separatorchar": ",", "skiplines": 0 "adaptertype": "CSV" "datasource": "href": " "id": "2", "name": "Uploads" "effectivepermissions": 38, "fields": [ "abbreviation": "Geographic Area", "id": "111", "includeoriginalvalue": true, "kind": "BASE", "name": "Geographic Area", "role": "VALUE", "type": "STRING", "version": " F5E" "abbreviation": "7/1/2010", "id": "112", "includeoriginalvalue": true, "kind": "BASE", "name": "7/1/2010", "role": "VALUE", "type": "INTEGER", "version": " F5F" "abbreviation": "July 1, 2009", "id": "113", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2009", "role": "VALUE", Page 91

92 API Reference Guide - datasets Resource "type": "STRING", "version": " F60" "abbreviation": "July 1, 2008", "id": "114", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2008", "role": "VALUE", "type": "STRING", "version": " F61" "abbreviation": "July 1, 2007", "id": "115", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2007", "role": "VALUE", "type": "STRING", "version": " F62" "abbreviation": "July 1, 2006", "id": "116", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2006", "role": "VALUE", "type": "STRING", "version": " F63" "abbreviation": "July 1, 2005", "id": "117", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2005", "role": "VALUE", "type": "STRING", Page 92

93 API Reference Guide - datasets Resource "version": " F64" "abbreviation": "July 1, 2004", "id": "118", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2004", "role": "VALUE", "type": "STRING", "version": " F65" "abbreviation": "July 1, 2003", "id": "119", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2003", "role": "VALUE", "type": "STRING", "version": " F66" "abbreviation": "July 1, 2002", "id": "120", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2002", "role": "VALUE", "type": "STRING", "version": " F67" "abbreviation": "July 1, 2001", "id": "121", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2001", "role": "VALUE", "type": "STRING", "version": " F68" Page 93

94 API Reference Guide - datasets Resource "abbreviation": "July 1, 2000", "id": "122", "includeoriginalvalue": true, "kind": "BASE", "name": "July 1, 2000", "role": "VALUE", "type": "STRING", "version": " F69" "abbreviation": "April Estimates Base", "id": "123", "includeoriginalvalue": true, "kind": "BASE", "name": "April Estimates Base", "role": "VALUE", "type": "STRING", "version": " F6A" "abbreviation": "April Census", "id": "124", "includeoriginalvalue": true, "kind": "BASE", "name": "April Census", "role": "VALUE", "type": "STRING", "version": " F6B" "abbreviation": "column 14", "hidden": true, "id": "125", "includeoriginalvalue": true, "kind": "BASE", "name": "column 14", "role": "VALUE", "type": "STRING", "version": " F6C" Page 94

95 API Reference Guide - datasets Resource "abbreviation": "Total Records", "autogenerated": true, "dependencies": [ "description": "System generated total record count (cannot be edited or deleted)", "expression": "COUNT()", "id": "126", "kind": "MEASURE", "name": "record count", "role": "MEASURE", "type": "LONG", "version": " F6D" "history": [ "lifecyclestage": "modified", "replaces": " DAB", "time": " T22:21:46.807Z", "user": "href": " "id": "5094" "version": " DAB" "lifecyclestage": "created", "replaces": null, "time": " T22:21:46.807Z", "user": "href": " "id": "5094" "version": " DAB" "href": " "id": "5", "key": [ "abbreviation": "Geographic Area", "id": "111", "includeoriginalvalue": true, "kind": "BASE", "name": "Geographic Area", "role": "VALUE", "type": "STRING", Page 95

96 API Reference Guide - datasets Resource "version": " F5E" "name": "US Pop by State", "objectpermissions": "Create": [ "memberid": -1, "type": "GROUP" "DataAccess": [ "memberid": -1, "type": "GROUP" "Owner": [ "memberid": 5094, "type": "USER" "version": " F5D" List a Dataset Use the GET method to list the dataset identified by its specified identifier (ID). URL /api/v1/datasets/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 96

97 API Reference Guide - datasets Resource Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response Returns the dataset with the ID given in the URL. Create Datasets Use the POST method to create a single dataset. You can only create one dataset at a time. This allows Platfora to return a different HTTP response code for each dataset. URL /api/v1/datasets HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters "data": "datasets": [ "abbreviation": "string", "adapter": "adapterdetails": "delimdefinition": [ "encoding": "UTF-8", "escapechar": "", "filter": "", Page 97

98 API Reference Guide - datasets Resource "hasheader": (true false), "islinebased": (true false), "maxlinelength": integer, "path": "string", "quotechar": "", "recordseparator": null, "regex": "", "separatorchar": "string", "skiplines": integer, "usesequencefile": (true false) "adaptertype": "(CSV HIVE PROTON APACHE REGEX LINE JSON AVRO JAVA DYNAMIC XML)" "datasource": "href": "string", "id": integer, "name": "string" "dependencies": [ "datasetid": integer, "datasetversion": "hexadecimal" "fields": [ "abbreviation": "string", "description": "string", "expression": "string", "hidden": (false true), "kind": "(REFERENCE BASE MEASURE COMPUTED)", "name": "string", "target": "datasetid": "integer", "foreignkey": [ "id": integer, "name": "string"... "type": "(REFERENCE DATETIME STRING INTEGER LONG DOUBLE)",... "key": [ "kind": "(BASE MEASURE COMPUTED)", "name": integer Page 98

99 API Reference Guide - datasets Resource "name": "string", "partitioningkey": "", Sample Call This sample POST body creates a dataset called requests_t using the Uploads data source. The Platfora server assigns an ID value to the dataset as it creates the dataset. "data": "datasets": [ "abbreviation": "requests_t", "adapter": "adapterdetails": "delimdefinition": [ "encoding": "UTF-8", "escapechar": "", "filter": "", "hasheader": true, "islinebased": false, "maxlinelength": , "path": "requests.tsv", "quotechar": "", "recordseparator": null, "regex": "", "separatorchar": "\t", "skiplines": 0, "usesequencefile": false "adaptertype": "CSV" "datasource": "href": " datasources/2", "id": "2", "name": "Uploads" "fields": [ "abbreviation": "id", "description": "primary key", "kind": "BASE", "name": "id", "type": "INTEGER" Page 99

100 API Reference Guide - datasets Resource request", service the request", request", dataset", request", "abbreviation": "time", "description": "request datetime", "kind": "BASE", "name": "time", "type": "DATETIME" "abbreviation": "bytes", "description": "bytes delivered for the "kind": "BASE", "name": "bytes", "type": "INTEGER" "abbreviation": "duration", "description": "how long in seconds it took to "kind": "BASE", "name": "duration", "type": "DOUBLE" "abbreviation": "bandwidth", "description": "average bandwidth to service the "expression": "bytes * 8 / duration / ", "kind": "COMPUTED", "name": "bandwidth_mps_raw", "type": "DOUBLE" "abbreviation": "server_id", "description": "foreign key into the servers "kind": "BASE", "name": "server_id", "type": "INTEGER" "abbreviation": "edge server", "description": "edge server that serviced the "kind": "REFERENCE", "name": "edge server", "target": Page 100

101 API Reference Guide - datasets Resource dataset", "datasetid": "6", "datasetversion": 2e+40, "foreignkey": [ "id": 1918, "name": "server_id" "type": "REFERENCE" "abbreviation": "# Records", "description": "total number of rows in the "expression": "COUNT()", "kind": "MEASURE", "name": "Total Records", "type": "LONG" "abbreviation": "Total Bytes", "description": "total bytes delivered", "expression": "SUM(bytes)", "kind": "MEASURE", "name": "Total Bytes Delivered", "type": "LONG" "key": [ "kind": "BASE", "name": "id" "name": "requests_test", "partitioningkey": "" Success Response This body response is returned when the dataset defined in the POST request is successfully created. It lists the dataset defined the body of the POST request, including additional information, such as the size in bytes. HTTP status return code: 201 Page 101

102 API Reference Guide - datasets Resource HTTP Body content: "_links":... "_metadata":... "data": "datasets": [ "abbreviation": "requests_test", "adapter": "adapterdetails": "delimdefinition": [ "encoding": "UTF-8", "escapechar": "", "filter": "", "hasheader": true, "islinebased": false, "maxlinelength": , "path": "requests.tsv", "quotechar": "", "recordseparator": null, "regex": "", "separatorchar": "\t", "skiplines": 0, "usesequencefile": false "adaptertype": "CSV" "datasource": "href": " datasources/2", "id": "2", "name": "Uploads" "fields": [ "abbreviation": "id", "description": "primary key", "id": "130", "includeoriginalvalue": true, "kind": "BASE", "name": "id", Page 102

103 API Reference Guide - datasets Resource request", service the request", "role": "VALUE", "type": "INTEGER", "version": " C" "abbreviation": "time", "description": "request datetime", "id": "131", "includeoriginalvalue": true, "kind": "BASE", "name": "time", "role": "VALUE", "type": "DATETIME", "version": " D" "abbreviation": "bytes", "description": "bytes delivered for the "id": "132", "includeoriginalvalue": true, "kind": "BASE", "name": "bytes", "role": "VALUE", "type": "INTEGER", "version": " E" "abbreviation": "duration", "description": "how long in seconds it took to "id": "133", "includeoriginalvalue": true, "kind": "BASE", "name": "duration", "role": "VALUE", "type": "DOUBLE", "version": " F" "abbreviation": "bandwidth", "dependencies": [ Page 103

104 API Reference Guide - datasets Resource request", dataset", request", "path": [ "id": "133", "name": "duration", "version": " F" "path": [ "id": "132", "name": "bytes", "version": " E" "description": "average bandwidth to service the "expression": "bytes * 8 / duration / ", "id": "134", "includeoriginalvalue": true, "kind": "COMPUTED", "name": "bandwidth_mps_raw", "role": "VALUE", "type": "DOUBLE", "version": " " "abbreviation": "server_id", "description": "foreign key into the servers "id": "135", "includeoriginalvalue": true, "kind": "BASE", "name": "server_id", "role": "VALUE", "type": "INTEGER", "version": " " "abbreviation": "edge server", "description": "edge server that serviced the Page 104

105 API Reference Guide - datasets Resource datasets/6" dataset", "id": "136", "kind": "REFERENCE", "name": "edge server", "role": "REFERENCE", "target": "datasetid": "6", "datasetname": "edge server", "datasetversion": " FFA", "foreignkey": [ "id": "135", "name": "server_id" "href": " "type": "REFERENCE", "version": " " "abbreviation": "# Records", "dependencies": [ "description": "total number of rows in the "expression": "COUNT()", "id": "137", "kind": "MEASURE", "name": "Total Records", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "Total Bytes", "dependencies": [ "path": [ "id": "132", "name": "bytes", "version": " E" "description": "total bytes delivered", "expression": "SUM(bytes)", Page 105

106 API Reference Guide - datasets Resource datasets/1" "id": "138", "kind": "MEASURE", "name": "Total Bytes Delivered", "role": "MEASURE", "type": "LONG", "version": " " "abbreviation": "time Date", "autogenerated": true, "description": "Automatic reference to Date", "id": "139", "kind": "REFERENCE", "name": "time Date", "role": "REFERENCE", "target": "datasetid": "1", "datasetname": "Date", "datasetversion": " ", "foreignkey": [ "id": "131", "name": "time" "href": " "type": "REFERENCE", "version": " " "abbreviation": "time Time", "autogenerated": true, "description": "Automatic reference to Time", "id": "140", "kind": "REFERENCE", "name": "time Time", "role": "REFERENCE", "target": "datasetid": "2", "datasetname": "Time", "datasetversion": " ", "foreignkey": [ "id": "131", "name": "time" Page 106

107 API Reference Guide - datasets Resource datasets/2" users/7", "href": " "type": "REFERENCE", "version": " " "history": [ "lifecyclestage": "created", "replaces": null, "time": " T00:33:03.210Z", "user": "href": " "id": "7" "version": " B" "href": " "id": "7", "key": [ "abbreviation": "id", "description": "primary key", "id": "130", "includeoriginalvalue": true, "kind": "BASE", "name": "id", "role": "VALUE", "type": "INTEGER", "version": " C" "name": "requests_test", "objectpermissions": "Owner": [ "memberid": 7, "type": "USER" "version": " B" Page 107

108 Chapter 6 lenses Resource Use the lenses resource to create a lens or list a collection of lenses in Platfora. Topics: Overview List All Lenses List a Lens Create Lenses Overview A lens is a Platfora object that represents data for a specific analysis project. A lens is defined, built, and then used in a project. Lens data can come from one or more datasets. You can use Platfora to view or create both aggregate lenses and event series lenses. Differences between Aggregate and Event Series Lenses Aggregate lenses typically include fields from a single fact dataset. Fact datasets contain data (measure and/or dimension) from a specific event such as a sales transaction or a page view. An aggregate lens groups the data by one or more dimensions. Imagine a dataset that details each sale in a region, how much the sale was, and when the sale happened. An aggregated lens of this data may sum total sales by region. An event series relies on two datasets. One dataset, called a focus, has a primary key that references records from one or more associated datasets. The associated dataset must include a timestamp field. An event series lens orders records first by the focus' primary key and secondarily by the timestamp. In this way, you can see each event for a specific primary key in the order in which each event happened. In addition to the common attributes, the lenses resource has the following attributes: Attribute abbreviation description Description Identical to the name attribute. Describes the lens contents. Page 108

109 API Reference Guide - lenses Resource Attribute datasets focusdataset Description Contains an array of data sets that the lens relies on. Specifies the focus of an event series lens. This attribute is empty if eventbased is false. focusdatasetkey Specifies the primary key used to create an event series lens. This attribute is empty if eventbased is false. fields filters drilldowns eventbased buildsummaries Contains a list of field structures representing the fields the lens uses. Contains an array of filter objects. Contains an array of drill downs defined in the lens. A drill down is a path from the most summarized to the most detailed categorization of a particular dimension. Indicates whether the lens is an event series lens or not. This is a boolean value. Summarizes the lens' build history. If a build was attempted, includes the LastAttempt structure. If a build was attempted and successful, the summary also describes a LastSucessful structure. The fields structure has the following content: Attribute name type Description Contains the name. Specifies the data type the field contains. Can be one of: INTEGER STRING DOUBLE LONG DATETIME CURRENCY REFERENCE role Specifies the field's role in the lens: MEASURE REFERENCE VALUE (same as dimension) target Contains a JSON structure for resolving a reference field. Not required for MEASURE or VALUE fields. Page 109

110 API Reference Guide - lenses Resource Attribute expression lensexpression children Description Contains the expression from the dataset. Contains a boolean that identifies Map of name to LensField JSON objects platforamanaged Indicates whether the lens field is generated and managed by Platfora instead of by the user. List All Lenses Use the GET method to retrieve and list the lenses currently configured in Platfora. URL /api/v1/lenses HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all lenses defined in Platfora. HTTP status return code: 200 HTTP Body content: Page 110

111 API Reference Guide - lenses Resource "data": "lenses": [ "id": "42", "name": "25 plus (Segment Refresh Prerequisites)", "version": " F6F", "objectpermissions": "Owner": [ "memberid": 1402, "type": "USER" "DataAccess": [ "memberid": -1, "type": "GROUP" "effectivepermissions": 32, "abbreviation": "25 plus (Segment Refresh Prerequisites)", "focusdataset": "href": " datasets/4", "id": "4", "name": "NFL Games" "fields": "NFL Players": "name": "NFL Players", "children": "Age": "name": "Age", "expression": "TO_INT(YEAR_DIFF( TRUNC(TO_DATE(\"2014\", \"yyyy\"), \"year\"), TRUNC(BirthDate, \"year\")))", "lensexpression": false, "platforamanaged": false, "role": "VALUE", "type": "INTEGER" "PlayerID": "name": "PlayerID", "lensexpression": false, "platforamanaged": false, "role": "VALUE", "type": "INTEGER" "lensexpression": false, "platforamanaged": false, Page 111

112 API Reference Guide - lenses Resource api/v1/datasets/3", v1/datasets/4", v1/datasets/3", "role": "REFERENCE", "target": "href": " "id": "3", "name": "NFL Players" "type": "REFERENCE" "Total Records": "name": "Total Records", "expression": "COUNT()", "lensexpression": false, "platforamanaged": false, "role": "MEASURE", "type": "LONG" "filters": [ "comparison": " > 25", "fieldpath": "path": [ "id": "1739", "name": "NFL Players", "version": " A690" "id": "5536", "name": "Age", "version": " FBBA" "type": "DERIVED_DATASET_PREREQUISITES", "eventbased": false, "buildsummaries": "datasets": [ "href": " "id": "4", "name": "NFL Games" "href": " "id": "3", "name": "NFL Players" Page 112

113 API Reference Guide - lenses Resource v1/datasets/2", "href": " "id": "2", "name": "Time" "href": " v1/datasets/1", "id": "1", "name": "Date" "drilldowns": [ "focusdatasetkey": [ "history": [ "lifecyclestage": "created", "replaces": null, "time": " T16:36:58.681Z", "user": "href": " api/v1/users/1402", "id": "1402" "version": " F6F" "href": " lenses/42" "_metadata":... "_links":......array continues... List a Lens Use the GET method to get a specific lens. Page 113

114 API Reference Guide - lenses Resource URL /api/v1/lenses/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response Returns the lens with the ID given in the URL. Create Lenses Use the POST method to create a single lens. By only allowing one lens to be created at a time, Platfora can return a different HTTP response code for each lens. URL /api/v1/lenses HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Page 114

115 API Reference Guide - lenses Resource Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters "data": "lenses": [ "abbreviation": "string", "fields": "string_field_name": "deprecated": (true false), "expression": "string", "hidden": (true false), "kind": "(REFERENCE BASE MEASURE MEASURE COMPUTED)", "name": "string_field_name", "type": "(REFERENCE DATETIME STRING INTEGER LONG DOUBLE)" "string_field_name": "children": "string": "lensexpression": (true false), "role": "VALUE", "type": "(REFERENCE DATETIME STRING INTEGER LONG DOUBLE)" "deprecated": (true false), "kind": "REFERENCE", "lensexpression": (true false), "targetdataset": "href": "string", "id": "integer", "name": "string" "type": "REFERENCE"... "focusdataset": "href": "string", "id": "integer", "name": "string" "focusdatasetkey": [ "id" "name": "string", Page 115

116 API Reference Guide - lenses Resource "size": 0 Sample Call This sample POST body creates a lens called bottom-up requests lens with bucketed geo using the bottom-up unbroken test dataset dataset. The Platfora server assigns an ID value to the lens as it creates the lens. "data": "lenses": [ "abbreviation": "bottom-up requests lens with bucketed geo", "fields": "Total Records": "expression": "COUNT()", "kind": "MEASURE", "name": "Total Records", "type": "LONG" "bandwidth_mps": "expression": "ROUND(bandwidth_mps_raw,0)", "kind": "COMPUTED", "name": "bandwidth_mps", "type": "DOUBLE" "colo": "children": "site": "lensexpression": false, "role": "VALUE", "type": "STRING" "kind": "REFERENCE", "lensexpression": false, "targetdataset": "href": " datasets/64", "id": "64", "name": "sites" Page 116

117 API Reference Guide - lenses Resource datasets/58", datasets/8", geo", "type": "REFERENCE" "customer": "children": "customer": "lensexpression": false, "role": "VALUE", "type": "STRING" "kind": "REFERENCE", "lensexpression": false, "targetdataset": "href": " "id": "58", "name": "customers" "type": "REFERENCE" "focusdataset": "href": " "id": "8", "name": "bottom-up unbroken test dataset" "focusdatasetkey": [ "id" "name": "bottom up cons-d requests lens with bucketed "size": 0 Success Response This body response is returned when the lens defined in the POST request is successfully created. It lists the lens defined the body of the POST request, including additional information. HTTP status return code: 201 HTTP Body content: "_links": "self": "href": " Page 117

118 API Reference Guide - lenses Resource "rel": "self", "title": "Lenses" "_metadata":... "data": "lenses": [ "abbreviation": "bottom-up requests lens with bucketed geo", "buildsummaries": "lastattempt": "id": "0", "status": "DEFINED", "time": " T00:37:13.709Z", "version": " B" "datasets": [ "href": " datasets/8", "id": "8", "name": "bottom-up unbroken test dataset" "href": " datasets/6", "id": "6", "name": "edge server" "href": " datasets/2", "id": "2", "name": "Time" "href": " datasets/1", "id": "1", "name": "Date" "drilldowns": [ "fields": "Total Records": "expression": "COUNT()", "lensexpression": false, "name": "Total Records", Page 118

119 API Reference Guide - lenses Resource datasets/8", users/7", geo", "role": "MEASURE", "type": "LONG" "filters": [ "focusdataset": "href": " "id": "8", "name": "bottom-up unbroken test dataset" "focusdatasetkey": [ "id" "history": [ "lifecyclestage": "created", "replaces": null, "time": " T00:37:10.973Z", "user": "href": " "id": "7" "version": " " "href": " "id": "4", "name": "bottom up cons-d requests lens with bucketed "objectpermissions": "Owner": [ "memberid": 7, "type": "USER" "version": " " Here is the response for a GET of the lens created above: "_links":... "_metadata": Page 119

120 API Reference Guide - lenses Resource... "data": "lenses": [ "abbreviation": "bottom-up requests lens with bucketed geo", "buildsummaries": "lastattempt": "id": "0", "status": "DEFINED", "time": " T00:37:16.911Z", "version": " D" "datasets": [ "href": " datasets/8", "id": "8", "name": "bottom-up unbroken test dataset" "href": " datasets/6", "id": "6", "name": "edge server" "href": " datasets/2", "id": "2", "name": "Time" "href": " datasets/1", "id": "1", "name": "Date" "drilldowns": [ "effectivepermissions": 61, "fields": "Total Records": "expression": "COUNT()", "lensexpression": false, "name": "Total Records", "role": "MEASURE", "type": "LONG" Page 120

121 API Reference Guide - lenses Resource datasets/8", users/7", geo", "filters": [ "focusdataset": "href": " "id": "8", "name": "bottom-up unbroken test dataset" "focusdatasetkey": [ "id" "history": [ "lifecyclestage": "created", "replaces": null, "time": " T00:37:10.973Z", "user": "href": " "id": "7" "version": " " "href": " "id": "4", "name": "bottom up cons-d requests lens with bucketed "objectpermissions": "Owner": [ "memberid": 7, "type": "USER" "version": " " Page 121

122 Chapter 7 lensbuilds Resource Use the lensbuilds resource to launch a lens build or list a build's status. Topics: Overview POST a Lens Build GET a Lens Build Overview The lensbuild resource allows you to launch a news lens build and then later retrieve information about it. A lensbuild resource has the following fields: Attribute lens buildend buildmessage buildstart createdby href id Description A structure describing the lens. This structure contains the lens' id and an href value. Timestamp representing when the build completed. This is not returned for builds that Current message on the build. Timestamp representing when the build started. A structure describing the user that started the lens build. This structure contains the user's id and an href value. The URL of the build resource. The internal system identifier for the build. Page 122

123 API Reference Guide - lensbuilds Resource Attribute status Description The build status. After a build starts but before it completes, the status is one of: UNDEFINED DEFINED SCHEDULED BUILDING CANCELING After a build completes, the status is one of: SUCCESSFUL CANCELED FAILED REMOVED ABORTED type This is set by the system and is reserved. POST a Lens Build Use the POST method to schedule a lens build in Platfora. URL /api/v1/lensbuilds HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Page 123

124 API Reference Guide - lensbuilds Resource Sample Call For POST requests, the body of the HTTP request should contain the id of the lens. "data": "lensbuilds": [ "lens": "id": "578" Success Response This response returns a lensbuilds structure: "data": "lensbuilds": [ "lens": "id": "578", "href": " lenses/578" "buildmessage": "Build is starting.", "buildstart": T21:38:36.473Z, "createdby": "id": "7", "href": " users/7" "href": " lensbuilds/ f5b", "id": " F5B", "status": "SCHEDULED", "type": "NORMAL" "_metadata":... "_links":... Page 124

125 API Reference Guide - lensbuilds Resource GET a Lens Build Use the GET method to retrieve a lens build. URL /api/v1/lensbuilds/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns a lensbuild description in the HTTP Body content: "data": "lensbuilds": [ "lens": "id": "578", "href": " lenses/578" "buildmessage": "In progress: Load dataset FlyingHigh", "buildstart": T21:38:36.473Z, "createdby": "id": "7", Page 125

126 API Reference Guide - lensbuilds Resource "href": " users/7" "href": " lensbuilds/ b8", "id": " B8", "status": "BUILDING", "type": "NORMAL" "_metadata":... "_links":... Page 126

127 Chapter 8 vizboards Resource Use the vizboards resource allows to create or list Platfora vizboards. Topics: Overview List Vizboards List a Vizboard Create Vizboard Overview Use this resource to list, create, or export visualizations. Reference title A vizboard is where data analysts create and manage visualizations around a particular project or subject area. A vizboard can contain one or more sheets (pages). Sheets (pages) can contain one or more visualizations. Each visualization can reference a different lens, and each lens can reference one or more datasets. Attribute vizboarddetails datasets lenses focusdatasets history Description Contains a structure describing the vizboard sheets and their contents (worksheets). Contains an array of the datasets objects. The focus datasets reference these datasets. Contains the array of lenses that provide data to visualizations on the board. Contains an array of the focus datasets. These focus datasets provide the basis for the lenses. Contains a history object array. This array shows the boards change history. Page 127

128 API Reference Guide - vizboards Resource Attribute href webuiinternal Description Contains the board's URI. Contains a structure documenting the displayed titles for the visualization and its sheets. The vizboarddetails structure has the following: Attribute pages worksheets Description Contains array of sheet objects. Sheets contain additional structures that describe it. Include is a panes array, one for each visualization on the page. Contains an array of visualization worksheets. activepageindex Identifies the currently active sheet. version title localfields Contains a Platfora tracked value. Contains the board's title. Contains an array of the visualization fields. List Vizboards Use the GET method to retrieve and list the vizboards currently configured in Platfora. Platfora recommends that the only vizboard field you edit is title inside vizboarddetails. URL /api/v1/vizboards HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 128

129 API Reference Guide - vizboards Resource Data Parameters None. Sample Call For GET requests, the Body of the HTTP request should be empty. Success Response This response returns all vizboards defined in Platfora. HTTP status return code: 200 HTTP Body content: "data": "vizboards": [ "id": "100", "name": " E156", "version": " E173", "objectpermissions": "Owner": [ "memberid": , "type": "USER" "Viewer": [ "memberid": -1, "type": "GROUP" "effectivepermissions": 38, "vizboarddetails": "pages": [ "title": "Page 1", "bounds": "width": 590, "height": 600 "settings": "overflow": "none", "autoscale": "none", "autoupdate": true "panes": [ Page 129

130 API Reference Guide - vizboards Resource "bounds": "left": 0, "top": 0, "right": 0, "bottom": 90 "index": 0 "worksheets": [ "guid": "f302dda6-13d0-4d9f-bcfb-779cfcbb6367", "title": "Visualization 1", "mode": "crosstab", "analysis": "stack": "auto" "visualization": "layout": "rectangular", "geometry": "auto", "interpolation": "auto", "color": "encoding": "auto" "column": "encoding": "auto" "fillcolor": "encoding": "auto" "strokecolor": "encoding": "auto" "opacity": "encoding": "auto" "fillopacity": "encoding": "auto" "strokeopacity": "encoding": "auto" "size": "encoding": "auto" "fillsize": "encoding": "auto" "row": "encoding": "auto" Page 130

131 API Reference Guide - vizboards Resource "strokesize": "encoding": "auto" "shape": "encoding": "auto" "text": "encoding": "auto" "interesttable": "name": "localname": "October 2012 Flight Data", "namespace": "default" "focus": "localname": "Flights", "namespace": "default" "version": " A", "buildversion": " " "fields": "column": [ "name": "Arrival Delay (AVG)", "label": "Arrival Delay (AVG)", "normalized": false, "scale": "linear", "includezeros": true, "format": "type": "type_normal", "precision": "2", "sign": "type_sign_minus" "row": [ "name": "Arrival Airport.State", "label": "Arrival Airport.State", "sort": "type": "default", "order": "asc" "interpretation": "discrete" "detail": [ "color": [ Page 131

132 API Reference Guide - vizboards Resource "opacity": [ "size": [ "shape": [ "text": [ "inputs": [ "successes": [ "trials": [ "fillcolor": [ "strokecolor": [ "fillopacity": [ "strokeopacity": [ "fillsize": [ "strokesize": [ "localfilter": [ "baselines": "type": "none" "filters": [ "zindex": 1, "settings": "automaticcalculation": "", Page 132

133 API Reference Guide - vizboards Resource "autoformat": "color": true, "opacity": true, "size": true "rendering": "mode": "auto" "activepageindex": 0, "version": " ", "title": "Flights Tutorial (Daria)", "localfields": [ "datasets": [ "href": " datasets/26", "id": "26", "name": "October 2012 Flight Data DDD" "href": " datasets/57", "id": "57", "name": "Arrival Airports in CA that have Flights cancelled Due to Weather" "href": " datasets/58", "id": "58", "name": "Arrival Airports in NY that have Flights Cancelled Due to Weather" "href": " datasets/2", "id": "2", "name": "Time" "href": " datasets/7", "id": "7", "name": "Airports" Page 133

134 API Reference Guide - vizboards Resource "href": " datasets/1", "id": "1", "name": "Date" "lenses": [ "href": " "id": "7", "name": "October 2012 Flight Data" "focusdatasets": [ "href": " datasets/8", "id": "8", "name": "Flights" "history": [ "lifecyclestage": "modified", "replaces": " E15C", "time": " T23:44:15.850Z", "user": "href": " users/ ", "id": " " "version": " E173" "lifecyclestage": "created", "replaces": null, "time": " T23:40:07.525Z", "user": "href": " users/ ", "id": " " "version": " E15C" "href": " vizboards/100", "webuiinternal": "title": "Flights Tutorial (Daria)", "viztitles": [ "Visualization 1" "pagetitles": [ Page 134

135 API Reference Guide - vizboards Resource "Page 1" "_metadata":... "_links":... List a Vizboard The vizboards/id resource allows you to create or list a particular instance of a vizboard. Use the GET method to list the vizboard identified by its specified identifier (ID). URL /api/v1/vizboards/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response Returns the vizboard with the ID given in the URL. Page 135

136 API Reference Guide - vizboards Resource Create Vizboard The vizboards resource allows you to create a vizboard or list a collection of vizboards in Platfora. Use the POST method to create a single vizboard. By only allowing one vizboard to be created at a time, Platfora can return a different HTTP response code for each vizboard. Platfora recommends that the only vizboard field you edit is title inside vizboarddetails. URL /api/v1/vizboards HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters When creating a vizboard using POST, ensure that the only data parameter included in the request Body is vizboarddetails, as shown below. Only use vizboard details text that was created by the Platfora API as a response to a GET to /api/v1/ vizboards or /api/v1/vizboards/id. You can change the title of the vizboard using the title parameter in the vizboarddetails string. Do not edit any other part of the vizboard details. The contents of the vizboarddetails parameter are subject to change in future Platfora releases. Do not edit any parameter other than the title parameter. "data": "vizboards": [ "vizboarddetails": vizboard_details_string Page 136

137 API Reference Guide - vizboards Resource Sample Call This sample POST body creates a vizboard titled COPY OF arrival delays. The Platfora server assigns an ID value to the vizboard as it creates the vizboard. In the example below, the title of the vizboard has been edited inside the vizboarddetails parameter using the following text: "title": "COPY OF arrival delays" "data": "vizboards": [ "vizboarddetails": "pages": [ "title": "Page 1", "bounds": "width": 1900, "height": 1220 "settings": "overflow": "none", "autoscale": "none", "autoupdate": true "panes": [ "bounds": "left": 0, "top": 0, "right": 0, "bottom": 183 "index": 0 "worksheets": [ "guid": "502de37c b98-b0fb-66bd02ca59c8", "title": "Visualization 1", "mode": "visualization", "analysis": "stack": "auto" "visualization": "layout": "rectangular", "geometry": "auto", "totals": "interpolation": "auto", Page 137

138 API Reference Guide - vizboards Resource "color": "encoding": "auto" "fillcolor": "encoding": "auto" "strokecolor": "encoding": "auto" "opacity": "encoding": "auto" "fillopacity": "encoding": "auto" "strokeopacity": "encoding": "auto" "size": "encoding": "auto" "fillsize": "encoding": "auto" "strokesize": "encoding": "auto" "shape": "encoding": "auto" "text": "encoding": "auto" "interesttable": "name": "localname": "October 2012 Flight Data", "namespace": "default" "focus": "localname": "Flights", "namespace": "default" "version": " ", "buildversion": " D6" "fields": "column": [ "name": "Arrival Delay (AVG)", "label": "Arrival Delay (AVG)", "normalized": false, "scale": "linear", Page 138

139 API Reference Guide - vizboards Resource "includezeros": true, "format": null "row": [ "name": "Arrival Airport.City", "label": "Arrival Airport.City", "sort": "type": "default", "order": "asc" "interpretation": "discrete" "detail": [ "color": [ "opacity": [ "size": [ "shape": [ "text": [ "inputs": [ "successes": [ "trials": [ "fillcolor": [ "strokecolor": [ "fillopacity": [ "strokeopacity": [ Page 139

140 API Reference Guide - vizboards Resource "fillsize": [ "strokesize": [ "localfilter": [ "baselines": "type": "none" "filters": [ "zindex": 1, "settings": "automaticcalculation": "", "autoformat": "color": true, "opacity": true, "size": true "rendering": "mode": "auto" "activepageindex": 0, "version": " ", "title": "COPY OF arrival delays", "localfields": [ Success Response This body response is returned when the vizboard defined in the POST request is successfully created. It lists the vizboard defined the body of the POST request, including additional information, such as its ID number. HTTP status return code: 201 Page 140

141 API Reference Guide - vizboards Resource HTTP Body content: "data": "vizboards": [ "id": "6", "name": " C", "version": " D", "objectpermissions": "Owner": [ "memberid": 7, "type": "USER" "vizboarddetails": "pages": [ "title": "Page 1", "bounds": "width": 1900, "height": 1220 "settings": "overflow": "none", "autoscale": "none", "autoupdate": true "panes": [ "bounds": "left": 0, "top": 0, "right": 0, "bottom": 183 "index": 0 "worksheets": [ "guid": "502de37c b98-b0fb-66bd02ca59c8", "title": "Visualization 1", "mode": "visualization", "analysis": "stack": "auto" "visualization": Page 141

142 API Reference Guide - vizboards Resource "layout": "rectangular", "geometry": "auto", "totals": "interpolation": "auto", "color": "encoding": "auto" "fillcolor": "encoding": "auto" "strokecolor": "encoding": "auto" "opacity": "encoding": "auto" "fillopacity": "encoding": "auto" "strokeopacity": "encoding": "auto" "size": "encoding": "auto" "fillsize": "encoding": "auto" "strokesize": "encoding": "auto" "shape": "encoding": "auto" "text": "encoding": "auto" "interesttable": "name": "localname": "October 2012 Flight Data", "namespace": "default" "focus": "localname": "Flights", "namespace": "default" "version": " ", "buildversion": " D6" "fields": Page 142

143 API Reference Guide - vizboards Resource "column": [ "name": "Arrival Delay (AVG)", "label": "Arrival Delay (AVG)", "normalized": false, "scale": "linear", "includezeros": true, "format": null "row": [ "name": "Arrival Airport.City", "label": "Arrival Airport.City", "sort": "type": "default", "order": "asc" "interpretation": "discrete" "detail": [ "color": [ "opacity": [ "size": [ "shape": [ "text": [ "inputs": [ "successes": [ "trials": [ "fillcolor": [ "strokecolor": [ Page 143

144 API Reference Guide - vizboards Resource "fillopacity": [ "strokeopacity": [ "fillsize": [ "strokesize": [ "localfilter": [ "baselines": "type": "none" "filters": [ "zindex": 1, "settings": "automaticcalculation": "", "autoformat": "color": true, "opacity": true, "size": true "rendering": "mode": "auto" "activepageindex": 0, "version": " ", "title": "COPY OF arrival delays", "localfields": [ "datasets": [ "href": " "id": "2", "name": "Time" "href": " "id": "3", Page 144

145 API Reference Guide - vizboards Resource "name": "Airports" "href": " "id": "1", "name": "Date" "lenses": [ "href": " "id": "1", "name": "October 2012 Flight Data" "focusdatasets": [ "href": " "id": "4", "name": "Flights" "history": [ "lifecyclestage": "created", "replaces": null, "time": " T00:23:09.302Z", "user": "href": " "id": "7" "version": " D" "href": " "_metadata":... "_links":... Page 145

146 Chapter 9 labels Resource Use the labels resource to list labels or create, update, or delete a label. Topics: Overview List All Labels List a Label Create a Label Update a Label Delete a Particular Label Overview A label is a tag that you can assign to Platfora datasets, lenses, segments, and vizboards to classify objects together. Labels allow you to organize and categorize Platfora objects for easier search and collaboration. Label Attributes Labels can be nested, so each label has a parent label. The highest level in the label hierarchy is the "All" label which is defined by Platfora. The labels resource has the following common attributes: name id namespace href In addition, it has the following attribute: Attribute parent Description Specifies the parent label that is one level higher than this label. When the parent label is the "All" label, no parent attribute is defined. Page 146

147 API Reference Guide - labels Resource List All Labels Use the GET method to retrieve and list the labels currently configured in Platfora. URL /api/v1/labels HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all labels defined in Platfora. HTTP status return code: 200 HTTP Body content: "data": "labels": [ "name": "Flights Tutorial", "id": "1", "namespace": "default", "href": " "name": "Geo Install", "id": "3", "namespace": "default", Page 147

148 API Reference Guide - labels Resource "href": " "name": "movies", "id": "4", "namespace": "default", "href": " "name": "Tutorial-Jennie", "parent": "id": "1", "href": " "id": "2", "namespace": "default", "href": " "_metadata": "offset": 0, "count": 4, "maxrecords": 4, "message": "Successful call to get list of labels.", "messagei18n": "Successful call to get list of labels.", "developermessage": "Successful call to get list of labels.", "valuemap": "error": false, "apiversion": "1.0", "requesttime": " T01:09:45.296Z", "responsetime": " T01:09:45.303Z", "status": 200, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labels" List a Label Use the GET method to list the label identified by its specified identifier (ID). Page 148

149 API Reference Guide - labels Resource URL /api/v1/labels/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns the label with the ID given in the URL. HTTP status return code: 200 The following text shows the HTTP Body content that is returned when getting the label with an ID of 2: "data": "labels": [ "name": "Western Region", "parent": "id": "1", "href": " "id": "2", "namespace": "default", "href": " "_metadata": "offset": 0, Page 149

150 API Reference Guide - labels Resource "count": 1, "maxrecords": 1, "message": "Successful call to get labels: 2", "messagei18n": "Successful call to get labels: 2", "developermessage": "Successful call to get labels: 2", "valuemap": "id": "2" "error": false, "apiversion": "1.0", "requesttime": " T23:41:48.743Z", "responsetime": " T23:41:48.745Z", "status": 200, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labels" Create a Label Use the POST method to create a single label. You can only create one label at a time. This allows Platfora to return a different HTTP response code for each label. URL /api/v1/labels HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Page 150

151 API Reference Guide - labels Resource Data Parameters The parent attribute is optional. Use it to to create a label as a child under another (parent) label. If the parent attribute is not included, Platfora places the label under "All." "data": "labels": [ "name": "string", "parent": "id": "integer" "namespace": "string" Sample Call This sample POST body creates a label called mylabel as a child to the label with an ID of 2. The Platfora server assigns an ID value to the label you creatae as it creates the label. "data": "labels": [ "name": "mylabel", "parent": "id": "2" "namespace": "default" Success Response This body response is returned when the label defined in the POST request is successfully created. It lists the label defined in the body of the POST request, including additional information, such as the ID assigned to it (in this example, the ID is ). HTTP status return code: 201 HTTP Body content: "data": "labels": [ Page 151

152 API Reference Guide - labels Resource "name": "mylabel", "parent": "id": "2", "href": " "id": "111358", "namespace": "default", "href": " "_metadata": "offset": 0, "count": 1, "maxrecords": 1, "message": "Successful call to create labels: mylabel", "messagei18n": "Successful call to create labels: mylabel", "developermessage": "Successful call to create labels: mylabel", "valuemap": "id": "111358", "name": "mylabel" "error": false, "apiversion": "1.0", "requesttime": " T23:51:36.584Z", "responsetime": " T23:51:36.599Z", "status": 201, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labels" Update a Label Use the PATCH method to modify a label configured in Platfora. You can only change the name of the label. URL /api/v1/labels Page 152

153 API Reference Guide - labels Resource HTTP Method PATCH Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters For PATCH requests, you can only change the name of the label. "data": "labels": [ "name": "string", "parent": "id": "integer" "namespace": "string" Sample Call This PATCH request updates the label with the ID of 999 and changes the label name to West. "data": "labels": [ "name": "West", "parent": "id": "88" "id": "999", "namespace": "default" Page 153

154 API Reference Guide - labels Resource Success Response This response returns the updated label defined in Platfora. HTTP status return code: 200 HTTP Body content: "data": "labels": [ "name": "West", "parent": "id": "88", "href": " "id": "999", "namespace": "default", "href": " "_metadata": "offset": 0, "count": 1, "maxrecords": 1, "message": "Successful call to update labels: 999", "messagei18n": "Successful call to update labels: 999", "developermessage": "Successful call to update labels: 999", "valuemap": "error": false, "apiversion": "1.0", "requesttime": " T18:42:13.668Z", "responsetime": " T18:42:13.676Z", "status": 200, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labels" Page 154

155 API Reference Guide - labels Resource Delete a Particular Label The labels/id resource allows you to modify, list, or delete a particular instance of a label. Use the DELETE method to delete the label identified by its specified identifier (ID). Deleting a label also deletes its corresponding label assignments, its children labels, and label assignments for its children labels. URL /api/v1/labels/id HTTP Method DELETE Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For DELETE requests, the Body of the HTTP request should be empty. Success Response The text below is returned in the HTTP response Body when the dataset of the ID specified in the URL of the DELETE call is successfully deleted. In this example, the label with an ID of was deleted: HTTP status return code: 200 HTTP Body content: "data": "_metadata": "offset": 0, "count": 1, "maxrecords": 1, "message": "Successful call to delete labels: ", "messagei18n": "Successful call to delete labels: ", Page 155

156 API Reference Guide - labels Resource "developermessage": "Successful call to deletelabels: ", "valuemap": "error": false, "apiversion": "1.0", "requesttime": " T23:38:23.800Z", "responsetime": " T23:38:23.828Z", "status": 200, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labels" Page 156

157 Chapter 10 labelassignments Resource Use the labelassignments resource to view or update a label that is assigned to a catalog object. Topics: Overview List All Label Assignments List a Label Assignment Create a Label Assignment Delete a Particular Label Assignment Overview A label assignment corresponds to a specific label that is assigned to a specific catalog object. A label assignment is created when a label is assigned to another object, not when a label is defined. If labels are defined, but none are assigned to any object, the response to a GET call will be empty. Label Attributes A label can be assigned to datasets, lenses, segments, and vizboards. Each catalog object can have zero or more labels assigned to it. Each labelassignment object includes a label identifier and a catalog object identifier. The labelassignments resource has the id and href common attributes in addition to the following attributes: Attribute label assignedobj Description Specifies the label that is assigned to a catalog object. This is specified by the label's unique identifier assigned by Platfora. Specifies the catalog object that has the specified lable assigned. This is specified by the object's unique identifier assigned by Platfora and also includes the object name and namespace. Page 157

158 API Reference Guide - labelassignments Resource List All Label Assignments Use the GET method to retrieve and list the label assignments currently configured in Platfora. URL /api/v1/labelassignments HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all label assignments defined in Platfora. HTTP status return code: 200 HTTP Body content: "data": "labelassignments": [ "label": "id": "1", "href": " "assignedobj": "id": "6", "namespace": "default", "name": "Airline Carriers", "objtype": "SourceTable", Page 158

159 API Reference Guide - labelassignments Resource "href": " "id": "1", "href": " "label": "id": "1", "href": " "assignedobj": "id": "5", "namespace": "default", "name": "Airports", "objtype": "SourceTable", "href": " "id": "2", "href": " "label": "id": "1", "href": " "assignedobj": "id": "7", "namespace": "default", "name": "Flights", "objtype": "SourceTable", "href": " "id": "3", "href": " "label": "id": "1", "href": " "assignedobj": "id": "9", "namespace": "default", "name": "Planes", "objtype": "SourceTable", "href": " "id": "4", "href": " "label": "id": "2", Page 159

160 API Reference Guide - labelassignments Resource "href": " "assignedobj": "id": "6", "namespace": "default", "name": "Airline Carriers", "objtype": "SourceTable", "href": " "id": "5", "href": " "label": "id": "2", "href": " "assignedobj": "id": "5", "namespace": "default", "name": "Airports", "objtype": "SourceTable", "href": " "id": "6", "href": " "label": "id": "2", "href": " "assignedobj": "id": "7", "namespace": "default", "name": "Flights", "objtype": "SourceTable", "href": " "id": "7", "href": " "label": "id": "2", "href": " "assignedobj": "id": "9", "namespace": "default", "name": "Planes", "objtype": "SourceTable", "href": " Page 160

161 API Reference Guide - labelassignments Resource "id": "8", "href": " "label": "id": "3", "href": " "assignedobj": "id": "19", "namespace": "default", "name": "US Cities", "objtype": "SourceTable", "href": " "id": "9", "href": " "label": "id": "3", "href": " "assignedobj": "id": "18", "namespace": "default", "name": "US Counties", "objtype": "SourceTable", "href": " "id": "10", "href": " "_metadata": "offset": 0, "count": 10, "maxrecords": 10, "message": "Successful call to get list of labelassignments.", "messagei18n": "Successful call to get list of labelassignments.", "developermessage": "Successful call to get list of labelassignments.", "valuemap": "error": false, "apiversion": "1.0", "requesttime": " T01:11:40.514Z", "responsetime": " T01:11:40.547Z", "status": 200, "code": " ", "platforaversion": "5.1.0" Page 161

162 API Reference Guide - labelassignments Resource "_links": "self": "href": " "rel": "self", "title": "labelassignments" List a Label Assignment Use the GET method to list the label assignment identified by its specified identifier (ID). URL /api/v1/labelassignments/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns the label assignment with the ID given in the URL. HTTP status return code: 200 The following text shows the HTTP Body content that is returned when getting the label assignment with an ID of 1: "data": Page 162

163 API Reference Guide - labelassignments Resource "labelassignments": [ "label": "id": "1", "href": " "assignedobj": "namespace": "default", "name": "Airline Carriers", "objtype": "SourceTable", "href": " "id": "1", "href": " "_metadata": "offset": 0, "count": 1, "maxrecords": 1, "message": "Successful call to get labelassignments: 1", "messagei18n": "Successful call to get labelassignments: 1", "developermessage": "Successful call to get labelassignments: 1", "valuemap": "id": "1" "error": false, "apiversion": "1.0", "requesttime": " T23:22:58.546Z", "responsetime": " T23:22:58.550Z", "status": 200, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labelassignments" Page 163

164 API Reference Guide - labelassignments Resource Create a Label Assignment Use the POST method to assign a label to a particular catalog object (a label assignment). You can only create one label assignment at a time. This allows Platfora to return a different HTTP response code for each label assignment. URL /api/v1/labelassignments HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters Use the following values for the objtype attribute: Dataset: SourceTable Lens: InterestTable Segment: SourceTable Vizboard: VizBoard "data": "labelassignments": [ "label": "id": "integer" "assignedobj": "namespace": "string", "name": "string", "objtype": "SourceTable InterestTable VizBoard" Page 164

165 API Reference Guide - labelassignments Resource Sample Call This sample POST body creates a label assignment that assigns the label with the ID of 3 to segment called prolific users. The Platfora server assigns an ID value to the label assignment as it creates the label assignment. "data": "labelassignments": [ "label": "id": "3" "assignedobj": "namespace": "default", "name": "prolific reviewers", "objtype": "SourceTable" Success Response This body response is returned when the label assignment defined in the POST request is successfully created. It lists the label assignment defined in the body of the POST request, including additional information, such as the ID assigned to it (in this example, the ID is ). HTTP status return code: 201 HTTP Body content: "data": "labelassignments": [ "label": "id": "3", "href": " "assignedobj": "namespace": "default", "name": "prolific reviewers", "objtype": "SourceTable", "href": " "id": "111370", "href": " labelassignments/111370" Page 165

166 API Reference Guide - labelassignments Resource "_metadata": "offset": 0, "count": 1, "maxrecords": 1, "message": "Successful call to create labelassignments: ", "messagei18n": "Successful call to create labelassignments: ", "developermessage": "Successful call to create labelassignments: ", "valuemap": "id": "111370" "error": false, "apiversion": "1.0", "requesttime": " T01:14:22.833Z", "responsetime": " T01:14:22.865Z", "status": 201, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " "rel": "self", "title": "labelassignments" Delete a Particular Label Assignment The labelassignments/id resource allows you to modify, list, or delete a particular labelassignment. Use the DELETE method to delete the label assignment identified by its specified identifier (ID). URL /api/v1/labelassignments/id HTTP Method DELETE Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Page 166

167 API Reference Guide - labelassignments Resource Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For DELETE requests, the Body of the HTTP request should be empty. Success Response The text below is returned in the HTTP response Body when the label assignment with the ID specified in the URL of the DELETE call is successfully deleted. In this example, the label assignment with an ID of was deleted: HTTP status return code: 200 HTTP Body content: "data": "_metadata": "offset": 0, "count": 1, "maxrecords": 1, "message": "Successful call to delete labelassignments: ", "messagei18n": "Successful call to delete labelassignments: ", "developermessage": "Successful call to deletelabelassignments: ", "valuemap": "error": false, "apiversion": "1.0", "requesttime": " T01:13:45.206Z", "responsetime": " T01:13:45.214Z", "status": 200, "code": " ", "platforaversion": "5.1.0" "_links": "self": "href": " labelassignments/111362", "rel": "self", "title": "labelassignments" Page 167

168 Chapter 11 query Resource Use the query resource to query a lens. Topics: Overview Query a Lens Lens Query Language Reference Overview The query resource allows you to query a Platfora lens. The query language allows you to ask the same questions programmatically as you could from the Vizboards page. A lens query is meant to support external applications that want to access Platfora lens data. When constructing the SELECT, you use Platfora's lens query language. For detailed instructions on using the query language, see Lens Query Language Reference. The resource supports passing the statement as a GET or POST with application/x-www-formurlencoded URL/form parameters. The caller must authenticate as a user with the Analyst (Limited) role or higher to execute a query. To query a specific lens, the caller must have Data Access on all datasets the lens references. A query resource can return results as comma separated values (CSV) stream or it can return a JSON body. CSV is the default output. The JSON body contains the following fields. Attribute query success columns rows Description A SELECT query that uses Platfora's lens query language. Whether the query was successful or not. A list of column names returned. Rows of data returned from the query. Page 168

169 API Reference Guide - query Resource Query a Lens Use the GET or POST method to query a Platfora lens. URL /api/v1/query HTTP Method GET or POST Required URL Parameters query=string Required. A SELECT query that uses Platfora's lens query language. See Lens Query Language Reference. If your query includes an = (equal) character you must URL encode it as %3D. Failure to encode the character can result in this error: string matching regex `(?i)\qnot\e\b' expected but end of source found. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. output=string Either csv or json output. If you don't supply a value, this call returns csv by default. Data Parameters None. Sample Call For GET or POST requests, pass the call x-www-form-urlencoded parameters. For example, to pass the following SELECT: SELECT [Unique Visitors FROM [200 ClickStream Aggregate You would use the following URL: +%5BClick+Time%5D+FROM+%5B200+ClickStream+Aggregate%5D+GROUP+BY+%5BClick +Time%5D&output=json Page 169

170 API Reference Guide - query Resource Success Response A successful call that requests csv output looks like the following: "[Unique Visitors" "200000" A successful call that requests json output looks like the following: "success":true, "query":"from [200 ClickStream Aggregate.[MT_200K_Clickstream measure [Unique Visitors", "columns":["[unique Visitors" "rows":[[ Error Response Unlike other Platfora REST APIs, this REST call cannot always distinguish user errors (400) from server errors (500). For example, if you query an event series lens as opposed to an aggregate lens, this is returned as a 500 error code even though it is a user error. You can rely on the developermessage field to return the message provided by Platfora's query message. "data": "_metadata": "offset": -1, "count": 0, "maxrecords": 0, "message": "Error occurred while trying to Query", "messagei18n": "Error occurred while trying to Query", "developermessage": "Error occurred while trying to Query. Details: Field not found: Unable to resolve the field or measure Applications. Either the specified field or measure does not exist in the lens or the specified field was not found in the GROUP BY clause", "valuemap": "error": true, "apiversion": "1.0", "code": " ", "requesttime": " T17:39:51.623Z", "responsetime": " T17:39:51.634Z", "status": 500 Page 170

171 API Reference Guide - query Resource Lens Query Language Reference Platfora's lens query language is a SQL-like language for programmatically querying the prepared data in a lens. This reference describes the query language syntax and usage. SELECT Statement Queries an aggregate lens. A SELECT statement is input to a progammatic lens query. Syntax [ DEFINE alias-name AS expression [ DEFINE... SELECT measure-field [ AS alias-name measure-expression AS alias-name [, dimension-field [ AS alias-name row-expression AS alias-name [,... FROM lens-name [ WHERE filter-expression [ AND filter-expression [ GROUP BY dimension-field [ [, group-ordering [ HAVING measure-filter-expression Description Use SELECT to query an aggregate lens. You cannot query an event series lens. The SELECT must include at least one measure field (column) or expression. Once you've supplied a measure value, your SELECT can contain additional measures or dimensions. If you include non-measure columns in the SELECT, you must include those columns in a GROUP BY clause. Use the DEFINE clause to add one or more computed fields to the lens. Platfora always queries the current version of the lens-name. Keep in mind lens definitions can change. If you write a query against a column that is later dropped from the lens, a previously working query can fail as a result and return an error message. Querying via REST A lens query is meant to support external applications that want to access Platfora lens data. For this reason, you query a lens by making API calls to the query REST resource: The resource supports passing the statement as a GET or POST with application/x-www-formurlencoded URL/form parameters. The caller must authenticate as a user with the Analyst (Limited) role or higher to execute a query. To query a specific lens, the caller must have Data Access on all datasets the lens references. A query returns comma separated values (CSV) by default. You have the option of receiving the results in a JSON body. For detailed information about using this REST APIs, see the Platfora API Reference. Page 171

172 API Reference Guide - query Resource Writing a SELECT Expression The SELECT expression can contain multiple columns and or expressions. You must specify at least one measure column or measure expression. Once you meet this requirement, you can include additional dimension columns or row expressions. Recall that a measure is a aggregate numeric value where as a dimension is a numeric, text, or time-based. A measure expression supports addition, subtraction, multiplication, and division. Inputs values can be column references (fields) or expressions that contain any of these supported functions: aggregate ( that is, AVG(), COUNT(), SUM() and so forth ROLLUP() EXP() POW() SQRT() Measure expressions can also include literal (integers or string) values. When constructing a measure expression, make sure you understand the expression syntax rules and limitations of aggregate functions. See the Expression and Query Language Reference for information on the aggregate function limitations and expression syntax. If the SELECT statement includes a dimension value, you must include the column in your GROUP BY clause. A dimension or row expression supports addition, subtraction, multiplication, and division of row values. Your SELECT can reference columns or supply row expressions that include following functions: data type conversion date and time general processing math string URL An expression can include literal (integers or string) values or other expressions. Make sure you understand the expression syntax rules. See the Expression and Query Language Reference for information on the expression syntax. When specifying an expression, supply an alias (AS clause) if you want to refer to the expression elsewhere in other clauses. You cannot use an * (asterisk) to retrieve all of the rows in a lens. Specifying Lens and Column Names When you specify the lens-name you use the name as it appears in the Data Catalog user interface. Enclose the name in [ (brackets) if it contains spaces or special characters. For example, you would refer to the Web Log-2014 lens as: [Web Log-2014 Page 172

173 API Reference Guide - query Resource When specifying a column name, you should follow the expression language rules for field (column) references. This means that for columns belonging to a reference dataset, you must qualify the name using dot-notation as follows: [ reference-dataset. [... column-name alias-name For example, use device.manufacturer to refer the manufacturer column in the device dataset. If you define an alias, use the alias to refer to the column in other parts of your query. DEFINE Clause Defines a computed field to include in a SELECT statement. DEFINE alias-name AS expression Use a DEFINE clause to include new computed fields that aren't in the original lens. Using the DEFINE clause is optional. Platfora applies the DEFINE statement before the main SELECT clause. New computed fields can only use fields already in the lens. The expression you write must be a valid expression for a vizboard computed field. This means your computed field is subject to the following restrictions: You can only define a computed field that operates on fields that exist in the lens. A vizboard computed field can break if it operates on fields that are later removed from the lens or a focus or referenced dataset. You cannot use aggregate functions to add new measures from dimension data in the lens. You can compute new measures from existing measures already in the lens. For example, if an AVG(sales) aggregate exists in the data, you can define a SUM(sales) field because SUM(sales) is necessary to compute AVG(sales). If you specify multiple DEFINE clauses, separate each new DEFINE with a space. A computed field can depend on any fields pre-existing in the lens or other fields created in the query's scope. For example, a computed field you DEFINE can depend on fields also created through other DEFINE statements. WHERE Clause Filters a lens query by one or more predicate expression. WHERE predicate-expression [ AND predicate-expression A predicate-expression can be a comparison: column-name = < > <= >=!= literal Or the predicate-expression can be a list-expression such as this: column-name [ NOT IN list LIKE pattern BETWEEN literal AND literal Page 173

174 API Reference Guide - query Resource Use WHERE clause to filter a lens query by one or more predicate expressions. Use the AND keyword to join multiple expressions. A WHERE clause can include expressions that make use of the comparison operators or list expressions. For detailed information about expressions syntax, see the Platfora Expression and Query Language Reference. You cannot useis NULL or IS NOT NULL comparisons in the WHERE clause. You also cannot use relative date filters (LAST integer DAYS) You can use the NOT keyword to negate any list expressions. The following example illustrate several different permutations of expressions structures you can use: SELECT count() FROM [View Summary WHERE prior_views NOT IN (3,5,7,11,13,17) AND TO_LONG(prior_views) NOT IN ( ) AND avebitrate_double NOT IN (3101.0, , 804.0) AND video.genre NOT IN ("Silent", "Exercise") AND video.genre NOT LIKE ("*a*") AND date.date NOT IN ( , , ) AND prior_views > 23 AND avebitrate_double < AND TO_FIXED(avebitrate_double)!= AND TO_LONG(prior_views)!= AND video.genre <= "Silent" AND date.date > AND date.date NOT BETWEEN AND AND video.genre BETWEEN "Exercise" and "Silent" AND prior_views BETWEEN 0 and 100 AND avebitrate_double NOT BETWEEN AND When comparing literal dates, make sure you use the format of yyyy-mm-dd without any enclosing quotation marks or other punctuation. GROUP BY Clause Orders and optionally limit the results of a SELECT statement. GROUP BY group-ordering [, group-ordering The group-ordering clause has the following syntax: column-name [ SORT [ BY measure-name [ ASC DESC [ LIMIT integer [ WITH OTHERS Use a GROUP BY clause to order and optionally limit results of a SELECT. If the SELECT statement includes a dimension column, you must supply GROUP BY clause that includes the dimension column. Otherwise, the GROUP BY clause is optional. A GROUP BY can include more than one column. To do this, delimit each column with a, (comma) as illustrated here: GROUP BY col_a, col_b, col_c Page 174

175 API Reference Guide - query Resource You can GROUP BY a new computed field that is not defined in the lens. To do this, you add the field using the DEFINE clause and then use the field in the GROUP BY clause. Alternatively, you can define the computed field in the SELECT list, associate an alias with the field, and use the alias in the GROUP BY clause. A SORT specification is optional. If you do not specify SORT, the query returns in an unspecified order. To sort the columns by their values ("natural sorting order"), simply specify ASC (ascending) or DESC (descending). ASC is the default SORT order when sorting by natural values. To SORT a particular column by another measure or measure expression use the SORT BY phrase. You can specify a measure-name in the SORT BY clause that need not be in the SELECT list. You can also order the sort in either ASC or DESC order. Unlike natural value sorts, SORT BY default to the DESC (descending) sorting order. GROUP BY col_a SORT BY meas_1 ASC, col_b SORT DESC, col_c SORT BY measure_expression ASC Using GROUP BY with multiple SORT BY combinations allows you to group values with respect to one another. Consider three potential grouping columns, say Fee, Fi, and Foe. Sorting on column Fee sorts the records on the Fee value. Another SORT BY clause on column Fi, sorts Fi values within the existing Fee sort. Use the LIMIT keyword to reduce the number of groups returned. For example, if you are sorting airports by the number of departing flights in DESC order (most flights to least flights), you could LIMIT the SORT to the 10 busiest airports. GROUP BY airports SORT BY total_departures DESC LIMIT 10 The LIMIT restricts the results to top 10 busiest departure airports. The LIMIT clause excludes other airports. You can use the WITH OTHERS keyword to combine all the other airports not in the top 10 under a single Others group. HAVING Clause Filters a SELECT statement by a measure expression. HAVING measure-predicate-expression [ AND measure-predicate-expression A measure-predicate-expression has the following form: measure-column measure-expression = < > <= >=!= literal The HAVING clause filters the result of the GROUP BY clause by a measure or measure expression. The HAVING conditions apply to the GROUP BY clause. SELECT device.manufacturer, [duration (Avg) FROM movie_view2g_psm GROUP BY device.manufacturer HAVING [duration (Max) = In the example above, you see a reference to two quick measure fields. Both the duration AVG() and MAX() quick measures are already defined on the lens. Page 175

176 API Reference Guide - query Resource Example of Lens Queries This section provides some tips and examples for querying a lens. When querying a lens, you must use the sql REST API endpoint. Before constructing your query, it is a good idea to list the lens fields with a REST call to the lens resource. One suggested method is to make the following calls: List the lens by calling GET on the resource. Locate the lens id value in the lens list. Get the lens by calling GET to the resource. Review the lens fields. This is one way to discover existing aggregate expressions and quick measures in the lens. For example, listing lens fields give you examples such as the following:... "fields": "Active Clusters (Total)": "name": "Active Clusters (Total)", "expression": "DISTINCT([Temp Field for Count Active Clusters)", "lensexpression": false, "platforamanaged": false, "role": "MEASURE", "type": "LONG" "Are there new Active Clusters since Yesterday?": "name": "Are there new Active Clusters since Yesterday?", "expression": "[Active Clusters (Total) - ROLLUP [Active Clusters (Total) TO ([Log DateTime Date.Date) ORDER BY ([Log DateTime Date.Date) ROWS BETWEEN 1 PRECEDING AND 1 PRECEDING", "lensexpression": false, "platforamanaged": false, "role": "MEASURE", "type": "LONG" "Avg Page Views per Session": "name": "Avg Page Views per Session", "expression": "[Total Records/(DISTINCT(sessionId))", "lensexpression": false, "platforamanaged": false, "role": "MEASURE", "type": "DOUBLE"... Using the JSON description of a lens, you can quickly see measures used in your lens versus navigating the lens in Platfora's UI. Page 176

177 API Reference Guide - query Resource This example illustrates the use of multiple DEFINE clauses. Notice the descriptive name for the ROLLUP() computed field. DEFINE Manu_Genre AS CONCAT ([device.[manufacturer [video.[genre) DEFINE [ROLLUP num_views TO Manu as ROLLUP COUNT() TO (device.manufacturer) DEFINE [ROLLUP num_views TO Manu_Genre as ROLLUP COUNT() TO ([Manu_Genre) SELECT device.manufacturer, Manu_Genre, [Num Views [ROLLUP num_views TO Manu [ROLLUP num_views TO Manu_Genre FROM moview_view2g_psm WHERE Manu_Genre LIKE (\"*Action/Comedy\", \"*Anime\", \"*Drama/Silent \") GROUP BY device.manufacturer SORT ASC, Manu_Genre SORT ASC HAVING [ROLLUP num_views TO Manu > AND [ROLLUP num_views TO Manu_Genre > 1000 The following example shows a WHERE clause using mixed predicates and row comparison. It also uses the NOT keyword to negate list expressions SELECT count() FROM [(test) View Summary WHERE prior_views NOT IN (3,5,7,11,13,17) AND TO_LONG(prior_views) NOT IN ( ) AND avebitrate_double NOT IN (3101.0, , 804.0) AND video.genre NOT IN ("Silent", "Exercise") AND video.genre NOT LIKE ("*a*") AND date.date NOT IN ( , , ) AND prior_views > 23 AND avebitrate_double < AND TO_FIXED(avebitrate_double)!= AND TO_LONG(prior_views)!= AND video.genre <= "Silent" and date.date > AND date.date NOT BETWEEN AND AND video.genre BETWEEN "Exercise" AND "Silent" AND prior_views BETWEEN 0 AND 100 AND avebitrate_double NOT BETWEEN AND You cannot use IS NULL or IS NOT NULL comparisons. You also cannot use relative date filters (LAST integer DAYS). The following example illustrates a measure expression that includes both a ROLLUP and use of aggregate functions. SELECT device.manufacturer, CONCAT([device.[manufacturer [video.[genre) AS Manu_Genre, [Num Views Page 177

178 API Reference Guide - query Resource ROLLUP COUNT() TO (device.manufacturer) as [ROLLUP num_views TO Manu ROLLUP COUNT() TO ([Manu_Genre) AS [ROLLUP num_views TO Manu_Genre FROM movie_view2g_psm WHERE Manu_Genre LIKE (\"*Action/Comedy\", \"*Anime\", \"*Drama/ Silent\") GROUP BY device.manufacturer SORT ASC, Manu_Genre SORT ASC HAVING [ROLLUP num_views TO Manu > AND [ROLLUP num_views TO Manu_Genre > 1000 This row expression uses multiple row terms and factors: SELECT duration + [days after release + user.age + user.location.estimatedpopulation AS [Row-Expression multi-factors [Num Views FROM movie_view2g_psm GROUP BY [Row-Expression multi-factors SORT ASC You'll notice that the Row-Expression multi-factors alias for the SELECT complex expression is reused in the GROUP BY clause. Page 178

179 Chapter 12 workflows Resource Use the workflows resource to create, edit, or list workflow resources. Topics: Overview List All Workflows List a Specific Workflow Create a Workflow Modify an Existing Workflow Delete a Workflow Overview The workflows resource represents task performed by Platfora. These tasks can occur immediately (ad hoc) or you can schedule them to reoccur on a regular basis. Currently, the workflows defined in Platfora are ones that render a vizboard as PDF and the PDF to one or more users. List All Workflows Use the GET method to retrieve and list the workflows currently configured in Platfora. URL /api/v1/workflows HTTP Method GET Required URL Parameters None. Page 179

180 API Reference Guide - workflows Resource Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all workflows defined in Platfora: "_links":... "_metadata":.. "data": "workflows": [ "alerts": [ "type": " ", "message": "", "name": "sample job", "recipients": [ "[email protected]" "subject": "Maps - GA - from scheduler", "href": " workflows/ /alerts/ ", "id": " ", "plaintext": true "enabled": true, "isadhoc": false, "schedules": [ "type": "WEEKLY", "hourlybased": false, "timezone": "US/Pacific", "times": [ Page 180

181 API Reference Guide - workflows Resource "11:15" "weekdays": [ 4 "href": " workflows/ /schedules/ ", "id": " " "type": "WEEKLY", "hourlybased": false, "timezone": "US/Pacific", "times": [ "11:17" "weekdays": [ 4 "href": " workflows/ /schedules/ ", "id": " " "type": "WEEKLY", "hourlybased": false, "timezone": "US/Pacific", "times": [ "14:51" "weekdays": [ 4 "href": " workflows/ /schedules/ ", "id": " " "type": "WEEKLY", "hourlybased": true, "hourlyinterval": 3, "hourlystarttime": 0, "timezone": "US/Pacific", "times": [ "weekdays": [ 1, 2, 3, 4, 5, 6, 7 Page 181

182 API Reference Guide - workflows Resource "href": " workflows/ /schedules/ ", "id": " " "vizreference": "kind": "id", "id": 493 "href": " workflows/ ", "id": " " "alerts": [ "type": " ", "message": "", "name": "sample job", "recipients": [ "[email protected]" "subject": "Copy of Analyst View2", "href": " workflows/ /alerts/ ", "id": " ", "plaintext": true "enabled": true, "isadhoc": false, "schedules": [ "type": "WEEKLY", "hourlybased": false, "timezone": "US/Pacific", "times": [ "09:00", "00:00", "02:00", "18:00" "weekdays": [ 1, 2, 3, 4, 5, 6, 7 "href": " workflows/ /schedules/ ", Page 182

183 API Reference Guide - workflows Resource "id": " " "vizreference": "kind": "id", "id": 259 "href": " workflows/ ", "id": " " List a Specific Workflow Use the GET method to retrieve and list a specific workflow currently configured in Platfora. URL /api/v1/workflows/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Page 183

184 API Reference Guide - workflows Resource Success Response This response returns a single workflow defined in Platfora: "_links":... "_metadata":... "data": "workflows": [ "alerts": [ "type": " ", "message": "", "name": "sample job", "recipients": [ "[email protected]" "subject": "Copy of Analyst View2", "href": " workflows/ /alerts/ ", "id": " ", "plaintext": true "enabled": true, "isadhoc": false, "schedules": [ "type": "WEEKLY", "hourlybased": false, "timezone": "US/Pacific", "times": [ "09:00", "00:00", "02:00", "18:00" "weekdays": [ 1, 2, 3, 4, 5, 6, 7 Page 184

185 API Reference Guide - workflows Resource "href": " workflows/ /schedules/ ", "id": " " "vizreference": "kind": "id", "id": 259 "href": " workflows/ ", "id": " " Create a Workflow Use the POST method to create an ad hoc or schedule a reoccurring workflow in Platfora. URL /api/v1/workflows HTTP Method POST Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For POST requests that schedule reoccurring tasks, the body of the HTTP request should contain the following: Page 185

186 API Reference Guide - workflows Resource "data": "workflows":[ "vizreference": "id":1 "enabled":true, "type":"render", "alerts":[ "type":" ", "subject":" Subject", "message":" Message", "isplaintext":true, "recipients":[ "[email protected]" "schedules":[ "type":"weekly", "weekdays":[ 1, 2, 3, 4, 5, 6, 7 "hourlystarttime":5, "hourlyinterval":2, "hourlybased":true, "timezone":"america/los_angeles" For POST requests that create adhoc tasks, the body of the HTTP request should contain the following: "data": "workflows":[ "vizreference": "id":2 "enabled":true, Page 186

187 API Reference Guide - workflows Resource attached", "isadhoc":true, "type":"render", "alerts":[ "type":" ", "subject":"adhoc PDF report", "message":"pdf generation successful and it has been "isplaintext":true, "recipients":[ "[email protected]" Success Response This response returns the new workflow defined in Platfora: "_links":... "_metadata":... "data": "workflows": [ "alerts": [ "type": " ", "message": " Message", "name": "sample job", "recipients": [ "[email protected]" "subject": " Subject", "href": " workflows/ /alerts/ ", "id": " ", "plaintext": true "enabled": true, "isadhoc": false, Page 187

188 API Reference Guide - workflows Resource "schedules": [ "type": "WEEKLY", "hourlybased": true, "hourlyinterval": 2, "hourlystarttime": 5, "timezone": "America/Los_Angeles", "times": [ "weekdays": [ 1, 2, 3, 4, 5, 6, 7 "href": " workflows/ /schedules/ ", "id": " " "vizreference": "kind": "id", "id": 1 "href": " workflows/ ", "id": " " Modify an Existing Workflow Use the PUT method to modify scheduled workflows currently configured in Platfora. URL /api/v1/workflows/id HTTP Method PUT Required URL Parameters None. Page 188

189 API Reference Guide - workflows Resource Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For PUT requests, the body of the HTTP request should contain a changed workflow structure. This call replaces the existing workflow with the new one. If you omit an attribute from the call's body, the call clears the attribute on the destination object. "_links":... "_metadata":... "data": "workflows": [ "alerts": [ "type": " ", "message": "", "name": "sample job", "recipients": [ "[email protected]" "subject": "nulltest_no_agg_viz", "href": " workflows/ /alerts/ ", "id": " ", "plaintext": true "enabled": true, "isadhoc": false, "schedules": [ "type": "MONTHLY", "days": [ 1 "starttime": "06:00", Page 189

190 API Reference Guide - workflows Resource "timezone": "US/Pacific", "href": " workflows/ /schedules/ ", "id": " " "vizreference": "kind": "id", "id": 498 "href": " workflows/ ", "id": " " Success Response This response returns the new workflow defined in Platfora. Delete a Workflow Use the DELETE method to delete a schedule workflow currently configured in Platfora. You cannot delete an adhoc workflow. URL /api/v1/workflows/id HTTP Method DELETE Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Page 190

191 API Reference Guide - workflows Resource Sample Call For DELETE requests, the body of the HTTP request should be empty. Success Response This response returns an empty workflow body. "_links":... "_metadata":... "data": If you attempt to delete an adhoc workflow, the server returns a 500 error. Page 191

192 Chapter 13 permissions Resource Use the permissions resource to create, edit, or view permissions. Topics: Overview List All Permissions PUT a permission PATCH a permission Overview The permissions resource represents a permission that applies to a Platfora object type. A permissions resource applies to an individual object of a particular type. The set of permissions for an object is the object's permissions group. The following individual permission applies to the object called Flights which is a Sourcetable object: "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Create", "href": " "name": "Flights", "objid": 7 Page 192

193 API Reference Guide - permissions Resource Each permission is granted to either a Platfora group or an individual user. The systempermissionset value can be one of the following object permissions: Permission Owner Description Gives the ability to create, update, delete, view the object metadata, and grant permissions. Edit Gives the ability to create, update, and view the object data. Create Viewer DataAccess Gives the ability to create and view the object data. Gives the ability to view the object data. Gives the ability to view the source data behind the object or any derivation of the source data. For example, this gives the ability to view the data source behind a lens. The DataAccess permission grants the ability to view data exposed by a data source. Data access is a binary control in Platfora. A user or group is either authorized to see the data or they are not. Once a user or group has data access, they will be able to see the data inside any object (dataset, lens, or vizboard) to which they also have object access permissions. The other permissions are hierarchical with Owner being the highest and Viewer the lowest. Having a permission higher in the hierarchy grants the permissions lower in the hierarchy. For example, if a user or group has Edit permission, then they also implicitly have Create and Viewer. The permission set for a resource is the combination of object access permissions and the data access setting. List All Permissions Use the GET method to retrieve and list the permissions configued in Platfora. Optionally, you can use some URL parameters to filter the list of permissions. URL /api/v1/permissions HTTP Method GET Required URL Parameters None. Page 193

194 API Reference Guide - permissions Resource Optional URL Parameters You can use URL parameters to filter the list of permissions. For example, you can return all permissions for datasets by escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. memberid=integer The unique identifier of the member this permission is granted to. membertype=string The type of permission, either USER or GROUP. objname=string The object's name. For vizboards, this is the unique identifier that Platfora assigns to the vizboard, not the visible title shown in the UI. objtype=string The type of object, either SourceTable (use for datasets and segments), InterestTable (use for lenses), DataSource, or VizBoard. permissiontype=string The permission level, either Owner, Edit, Create, Viewer, or DataAccess. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. By passing parameters you can filter the permissions. objname=flights&objtype=sourcetable Success Response This response returns all object permissions defined in Platfora: "_links": "self":... "_metadata":... Page 194

195 API Reference Guide - permissions Resource "data": "permissions": [ "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "DataAccess", "href": " "name": "Flights", "objid": 7 "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Create", "href": " "name": "Flights", "objid": 7 "memberid": 7, "membername": "admin", "membertype": "USER", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Owner", "href": " "name": "Flights", "objid": 7 Page 195

196 API Reference Guide - permissions Resource PUT a permission Use the PUT method to modify permission set for an object. A PUT call replaces the existing permission set with the new set. URL /api/v1/permissions HTTP Method PUT Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call This call operates against an object's permission set. If an object has three permissions and you want to modify one of them, you must pass the modified permission and the other permissions on the object. If you pass only the single modified permission, the call will remove the other permissions on the object. For PUT requests, the body of the HTTP request should contain each modified permission as well as the one you want to keep. "data": "permissions": [ "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "DataAccess", "href": " Page 196

197 API Reference Guide - permissions Resource "name": "Flights", "objid": 5 "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Edit", "href": " "name": "Flights", "objid": 5 "memberid": 7, "membername": "admin", "membertype": "USER", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Owner", "href": " "name": "Flights", "objid": 5 Success Response This response returns the updated permission set defined in Platfora. "_links": "self":... "_metadata":... "data": "permissions": [ "memberid": 7, "membername": "admin", "membertype": "USER", "namespace": "default", "objname": "Flights", Page 197

198 API Reference Guide - permissions Resource "objtype": "SourceTable", "systempermissionset": "Owner", "href": " "name": "Flights", "objid": 7 "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Edit", "href": " "name": "Flights", "objid": 7 "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "DataAccess", "href": " "name": "Flights", "objid": 7 PATCH a permission Use the PATCH method to modify permission currently configured in Platfora. Patch an object's permission set. You can add new permissions to objects or modify existing ones. The call modifies only the permissions for the user/object pairs that are PATCHed. URL /api/v1/permissions HTTP Method PATCH Page 198

199 API Reference Guide - permissions Resource Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For PATCH requests, the body of the HTTP request should contain at least one permission. You can add DataAccess permission with this call but to remove DataAccess from an object use the PUT call. "data": "permissions": [ "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Viewer", "href": " "name": "Flights", "objid": 7 Success Response This response returns the updated permissions set defined in Platfora. "_links":... "_metadata":... Page 199

200 API Reference Guide - permissions Resource "data": "permissions": [ "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "DataAccess", "href": " "name": "Flights", "objid": 7 "memberid": -1, "membername": "Everyone", "membertype": "GROUP", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Viewer", "href": " "name": "Flights", "objid": 7 "memberid": 7, "membername": "admin", "membertype": "USER", "namespace": "default", "objname": "Flights", "objtype": "SourceTable", "systempermissionset": "Owner", "href": " "name": "Flights", "objid": 7 Page 200

201 Chapter 14 renderjobs Resource Use the renderjobs resource to create, edit, or list a render job. Topics: Overview List All Render Jobs List a Specific Render Job Create a Render job Cancel a Render Job Overview The renderjobs resource represents the generation of vizboard as a PDF. Render jobs run at the next available slot in the job queue. Render jobs are meant to leave an audit trail. This trail allows you to see which vizboards were output to PDF. List All Render Jobs Use the GET method to retrieve and list the render jobs run in Platfora. URL /api/v1/renderjobs HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Page 201

202 API Reference Guide - renderjobs Resource Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Success Response This response returns all renderjobs defined in Platfora: "_links":... "_metadata":... "data": "renderjobs": [ "vizreference": "kind": "id", "id": 77 "createdby": "id": "370", "href": " "href": " renderjobs/ ", "id": " ", "jobtype": "ADHOC", "lastmodified": " T01:17:22Z", "result": " renderjobs/ /output", "started": " T01:17:14Z", "status": "SUCCESSFUL" "vizreference": "kind": "id", "id": 272 "createdby": "id": "1402", "href": " Page 202

203 API Reference Guide - renderjobs Resource "href": " renderjobs/ ", "id": " ", "jobtype": "ADHOC", "lastmodified": " T15:37:13Z", "result": " renderjobs/ /output", "started": " T15:35:33Z", "status": "SUCCESSFUL" List a Specific Render Job Use the GET method to retrieve and list a specific render job currently configured in Platfora. URL /api/v1/renderjobs/id HTTP Method GET Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For GET requests, the body of the HTTP request should be empty. Page 203

204 API Reference Guide - renderjobs Resource Success Response This response returns a single renderjob defined in Platfora: "_links":..." "_metadata":... "data": "renderjobs": [ "vizreference": "kind": "id", "id": 272 "createdby": "id": "1402", "href": " "href": " renderjobs/ ", "id": " ", "jobtype": "ADHOC", "lastmodified": " T15:37:13Z", "result": " renderjobs/ /output", "started": " T15:35:33Z", "status": "SUCCESSFUL" Create a Render job Use the POST method to create render job in Platfora. URL /api/v1/renderjobs HTTP Method POST Page 204

205 API Reference Guide - renderjobs Resource Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Sample Call For POST requests the body of the HTTP request should contain the following: "data": "renderjobs":[ "vizreference": "id":1 Success Response This response returns the new renderjob defined in Platfora: "_links":... "_metadata":... "data": "renderjobs": [ "vizreference": "kind": "id", "id": 1 Page 205

206 API Reference Guide - renderjobs Resource "createdby": "id": "7", "href": " "href": " renderjobs/ ", "id": " ", "jobtype": "ADHOC", "lastmodified": " T23:53:33Z", "started": " T23:53:33Z", "status": "SCHEDULED" Cancel a Render Job Use the PATCH method to modify render job currently configured in Platfora. Currently, the only change you can make is to cancel a job. URL /api/v1/renderjobs/id HTTP Method PATCH Required URL Parameters None. Optional URL Parameters escalatesuperadmin=boolean Either true or false. Allows the user making the call to run in Super Administrator mode. The user must be eligible to switch to Super Administrator mode. Data Parameters None. Page 206

207 API Reference Guide - renderjobs Resource Sample Call For PATCH requests, the body of the HTTP request should contain a single status attribute. "data": "renderjobs":[ "status" : "CANCELED" Success Response This response returns the updated renderjob defined in Platfora. "_links":... "_metadata":... "data": "renderjobs": [ "vizreference": "kind": "id", "id": 77 "createdby": "id": "7", "href": " "href": " renderjobs/ ", "id": " ", "jobtype": "ADHOC", "lastmodified": " T01:17:22Z", "result": " renderjobs/ /output", "started": "", "status": "CANCELED" Page 207

208 API Reference Guide - renderjobs Resource If you attempt to cancel a job that has completed or already in a non-canceable state, the system returns a 412 error code representing an invalid state transition. Page 208