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: support@platfora.com 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": "ariel@platfora.com", "effectiverole": "SuperAdmin", "href": " users/605441", "id": "605441", "type": "EXTERNAL", "username": "ariel@platfora.com" "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": "ariel@platfora.com", "effectiverole": "SuperAdmin", "href": " users/605441", "id": "605441", "type": "EXTERNAL", "username": "ariel@platfora.com" "_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": "laura@therose.com", "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": "ralph2@foobar.com" "_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": "bud@therose.com" 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": "bud@therose.com" "_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