Repository: kylin Updated Branches: refs/heads/1.x-staging e9afc45d3 -> 76397b67b
KYLIN-1296 Refine restful API document Project: http://git-wip-us.apache.org/repos/asf/kylin/repo Commit: http://git-wip-us.apache.org/repos/asf/kylin/commit/76397b67 Tree: http://git-wip-us.apache.org/repos/asf/kylin/tree/76397b67 Diff: http://git-wip-us.apache.org/repos/asf/kylin/diff/76397b67 Branch: refs/heads/1.x-staging Commit: 76397b67b8131f1f7cb6de45578a5d79d9cc27d0 Parents: e9afc45 Author: lidongsjtu <don...@ebay.com> Authored: Mon Jan 11 14:10:15 2016 +0800 Committer: lidongsjtu <don...@ebay.com> Committed: Mon Jan 11 14:23:44 2016 +0800 ---------------------------------------------------------------------- website/_dev/dev_env.md | 1 + .../howto/howto_build_cube_with_restapi.md | 39 +++--- website/_docs/howto/howto_jdbc.md | 80 ++++++------ website/_docs/howto/howto_use_restapi.md | 126 ++++++++++--------- website/_docs/howto/howto_use_restapi_in_js.md | 19 ++- website/_docs/index.md | 2 +- website/_docs/install/hadoop_evn.md | 4 +- 7 files changed, 140 insertions(+), 131 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_dev/dev_env.md ---------------------------------------------------------------------- diff --git a/website/_dev/dev_env.md b/website/_dev/dev_env.md index ec0d3fa..9eea9aa 100644 --- a/website/_dev/dev_env.md +++ b/website/_dev/dev_env.md @@ -23,6 +23,7 @@ ambari-server start {% endhighlight %} With both command successfully run you can go to ambari home page at <http://yoursandboxip:8080> (user:admin,password:admin) to check everything's status. By default ambari disables Hbase, you'll need manually start the `Hbase` service. + For other hadoop distribution, basically start the hadoop cluster, make sure HDFS, YARN, Hive, HBase are running. http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_docs/howto/howto_build_cube_with_restapi.md ---------------------------------------------------------------------- diff --git a/website/_docs/howto/howto_build_cube_with_restapi.md b/website/_docs/howto/howto_build_cube_with_restapi.md index ee4759c..4113700 100644 --- a/website/_docs/howto/howto_build_cube_with_restapi.md +++ b/website/_docs/howto/howto_build_cube_with_restapi.md @@ -3,7 +3,7 @@ layout: docs title: How to Build Cube with Restful API categories: howto permalink: /docs/howto/howto_build_cube_with_restapi.html -version: v1.0 +version: v1.2 since: v0.7.1 --- @@ -12,47 +12,44 @@ since: v0.7.1 * Add `Authorization` header to first request for authentication * Or you can do a specific request by `POST http://localhost:7070/kylin/api/user/authentication` * Once authenticated, client can go subsequent requests with cookies. -* Example {% highlight Groff markup %} - POST http://localhost:7070/kylin/api/user/authentication +POST http://localhost:7070/kylin/api/user/authentication - Authorization:Basic xxxxJD124xxxGFxxxSDF - Content-Type: application/json;charset=UTF-8 +Authorization:Basic xxxxJD124xxxGFxxxSDF +Content-Type: application/json;charset=UTF-8 {% endhighlight %} ### 2. Get details of cube. * `GET http://localhost:7070/kylin/api/cubes?cubeName={cube_name}&limit=15&offset=0` * Client can find cube segment date ranges in returned cube detail. -* Example {% highlight Groff markup %} - GET http://localhost:7070/kylin/api/cubes?cubeName=test_kylin_cube_with_slr&limit=15&offset=0 +GET http://localhost:7070/kylin/api/cubes?cubeName=test_kylin_cube_with_slr&limit=15&offset=0 - Authorization:Basic xxxxJD124xxxGFxxxSDF - Content-Type: application/json;charset=UTF-8 +Authorization:Basic xxxxJD124xxxGFxxxSDF +Content-Type: application/json;charset=UTF-8 {% endhighlight %} ### 3. Then submit a build job of the cube. * `PUT http://localhost:7070/kylin/api/cubes/{cube_name}/rebuild` -* For put request body detail please refer to [service doc](rest_api.html). +* For put request body detail please refer to [Build Cube API](howto_use_restapi.html#build-cube). * `startTime` and `endTime` should be utc timestamp. * `buildType` can be `BUILD` ,`MERGE` or `REFRESH`. `BUILD` is for building a new segment, `REFRESH` for refreshing an existing segment. `MERGE` is for merging multiple existing segments into one bigger segment. -* This method will return a newly created job instance, in which the uuid is the identity of job to track job status. -* Example +* This method will return a new created job instance, whose uuid is the unique id of job to track job status. {% highlight Groff markup %} - PUT http://localhost:7070/kylin/api/cubes/test_kylin_cube_with_slr/rebuild +PUT http://localhost:7070/kylin/api/cubes/test_kylin_cube_with_slr/rebuild - Authorization:Basic xxxxJD124xxxGFxxxSDF - Content-Type: application/json;charset=UTF-8 +Authorization:Basic xxxxJD124xxxGFxxxSDF +Content-Type: application/json;charset=UTF-8 - { - "startTime": 0, - "endTime": 1388563200000, - "buildType": "BUILD" - } +{ + "startTime": 0, + "endTime": 1388563200000, + "buildType": "BUILD" +} {% endhighlight %} ### 4. Track job status. * `GET http://localhost:7070/kylin/api/jobs/{job_uuid}` * Returned `job_status` represents current status of job. -### 5. If the job failed, you can resume the job. +### 5. If the job got errors, you can resume it. * `PUT http://localhost:7070/kylin/api/jobs/{job_uuid}/resume` http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_docs/howto/howto_jdbc.md ---------------------------------------------------------------------- diff --git a/website/_docs/howto/howto_jdbc.md b/website/_docs/howto/howto_jdbc.md index 45a2f4e..3e088fe 100644 --- a/website/_docs/howto/howto_jdbc.md +++ b/website/_docs/howto/howto_jdbc.md @@ -3,7 +3,7 @@ layout: docs title: How to Use kylin Remote JDBC Driver categories: howto permalink: /docs/howto/howto_jdbc.html -version: v0.7.2 +version: v1.2 since: v0.7.1 --- @@ -24,20 +24,20 @@ jdbc:kylin://<hostname>:<port>/<kylin_project_name> ### 1. Query with Statement {% highlight Groff markup %} - Driver driver = (Driver) Class.forName("org.apache.kylin.jdbc.Driver").newInstance(); +Driver driver = (Driver) Class.forName("org.apache.kylin.jdbc.Driver").newInstance(); - Properties info = new Properties(); - info.put("user", "ADMIN"); - info.put("password", "KYLIN"); - Connection conn = driver.connect("jdbc:kylin://localhost:7070/kylin_project_name", info); - Statement state = conn.createStatement(); - ResultSet resultSet = state.executeQuery("select * from test_table"); +Properties info = new Properties(); +info.put("user", "ADMIN"); +info.put("password", "KYLIN"); +Connection conn = driver.connect("jdbc:kylin://localhost:7070/kylin_project_name", info); +Statement state = conn.createStatement(); +ResultSet resultSet = state.executeQuery("select * from test_table"); - while (resultSet.next()) { - assertEquals("foo", resultSet.getString(1)); - assertEquals("bar", resultSet.getString(2)); - assertEquals("tool", resultSet.getString(3)); - } +while (resultSet.next()) { + assertEquals("foo", resultSet.getString(1)); + assertEquals("bar", resultSet.getString(2)); + assertEquals("tool", resultSet.getString(3)); +} {% endhighlight %} ### 2. Query with PreparedStatement @@ -56,39 +56,39 @@ jdbc:kylin://<hostname>:<port>/<kylin_project_name> * setTimestamp {% highlight Groff markup %} - Driver driver = (Driver) Class.forName("org.apache.kylin.jdbc.Driver").newInstance(); - Properties info = new Properties(); - info.put("user", "ADMIN"); - info.put("password", "KYLIN"); - Connection conn = driver.connect("jdbc:kylin://localhost:7070/kylin_project_name", info); - PreparedStatement state = conn.prepareStatement("select * from test_table where id=?"); - state.setInt(1, 10); - ResultSet resultSet = state.executeQuery(); +Driver driver = (Driver) Class.forName("org.apache.kylin.jdbc.Driver").newInstance(); +Properties info = new Properties(); +info.put("user", "ADMIN"); +info.put("password", "KYLIN"); +Connection conn = driver.connect("jdbc:kylin://localhost:7070/kylin_project_name", info); +PreparedStatement state = conn.prepareStatement("select * from test_table where id=?"); +state.setInt(1, 10); +ResultSet resultSet = state.executeQuery(); - while (resultSet.next()) { - assertEquals("foo", resultSet.getString(1)); - assertEquals("bar", resultSet.getString(2)); - assertEquals("tool", resultSet.getString(3)); - } +while (resultSet.next()) { + assertEquals("foo", resultSet.getString(1)); + assertEquals("bar", resultSet.getString(2)); + assertEquals("tool", resultSet.getString(3)); +} {% endhighlight %} -### 3. Get query result metadata +### 3. Get query result set metadata Kylin jdbc driver supports metadata list methods: List catalog, schema, table and column with sql pattern filters(such as %). {% highlight Groff markup %} - Driver driver = (Driver) Class.forName("org.apache.kylin.jdbc.Driver").newInstance(); - Properties info = new Properties(); - info.put("user", "ADMIN"); - info.put("password", "KYLIN"); - Connection conn = driver.connect("jdbc:kylin://localhost:7070/kylin_project_name", info); - Statement state = conn.createStatement(); - ResultSet resultSet = state.executeQuery("select * from test_table"); +Driver driver = (Driver) Class.forName("org.apache.kylin.jdbc.Driver").newInstance(); +Properties info = new Properties(); +info.put("user", "ADMIN"); +info.put("password", "KYLIN"); +Connection conn = driver.connect("jdbc:kylin://localhost:7070/kylin_project_name", info); +Statement state = conn.createStatement(); +ResultSet resultSet = state.executeQuery("select * from test_table"); - ResultSet tables = conn.getMetaData().getTables(null, null, "dummy", null); - while (tables.next()) { - for (int i = 0; i < 10; i++) { - assertEquals("dummy", tables.getString(i + 1)); - } - } +ResultSet tables = conn.getMetaData().getTables(null, null, "dummy", null); +while (tables.next()) { + for (int i = 0; i < 10; i++) { + assertEquals("dummy", tables.getString(i + 1)); + } +} {% endhighlight %} http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_docs/howto/howto_use_restapi.md ---------------------------------------------------------------------- diff --git a/website/_docs/howto/howto_use_restapi.md b/website/_docs/howto/howto_use_restapi.md index 5666f5b..27d4e7a 100644 --- a/website/_docs/howto/howto_use_restapi.md +++ b/website/_docs/howto/howto_use_restapi.md @@ -3,14 +3,14 @@ layout: docs title: How to Use Restful API categories: howto permalink: /docs/howto/howto_use_restapi.html -version: v1.0 +version: v1.2 since: v0.7.1 --- -This page lists all the Restful API that provided by Kylin; The endpoint of the Rest service is started with **/kylin/api**, so don't forget to add it before a certain API's path. For example, to get all cube instances, send HTTP GET request to "/kylin/api/cubes". +This page lists all the Rest APIs provided by Kylin; The base of the URL is `/kylin/api`, so don't forget to add it before a certain API's path. For example, to get all cube instances, send HTTP GET request to "/kylin/api/cubes". -* QUERY - * [Login](#login) +* Query + * [Authentication](#authentication) * [Query](#query) * [List queryable tables](#list-queryable-tables) * CUBE @@ -34,25 +34,16 @@ This page lists all the Restful API that provided by Kylin; The endpoint of the * Cache * [Wipe cache](#wipe-cache) -## Login +## Authentication `POST /user/authentication` -for example: - -``` -curl -c /path/to/cookiefile.txt -X POST -H "Authorization: Basic XXXXXXXXX" -H 'Content-Type: application/json' http://<host>:<port>/kylin/api/user/authentication -``` - -If login successfully, the JSESSIONID will be saved into the cookie file; In the subsequent http requests, attach the cookie, for example: - -``` -curl -b /path/to/cookiefile.txt -X PUT -H 'Content-Type: application/json' -d '{"startTime":'1423526400000', "endTime":'1423526400', "buildType":"BUILD"}' http://<host>:<port>/kylin/api/cubes/your_cube/rebuild -``` - -#### Header -Authorization data encoded by basic auth. Header sample: +#### Request Header +Authorization data encoded by basic auth is needed in the header, such as: Authorization:Basic {data} +#### Response Body +* userDetails - Defined authorities and status of current user. + #### Response Sample ```sh @@ -76,19 +67,33 @@ Authorization:Basic {data} } ``` +Example with `curl`: + +``` +curl -c /path/to/cookiefile.txt -X POST -H "Authorization: Basic XXXXXXXXX" -H 'Content-Type: application/json' http://<host>:<port>/kylin/api/user/authentication +``` + +If login successfully, the JSESSIONID will be saved into the cookie file; In the subsequent http requests, attach the cookie, for example: + +``` +curl -b /path/to/cookiefile.txt -X PUT -H 'Content-Type: application/json' -d '{"startTime":'1423526400000', "endTime":'1423526400', "buildType":"BUILD"}' http://<host>:<port>/kylin/api/cubes/your_cube/rebuild +``` + *** ## Query `POST /query` #### Request Body -* sql - `required` `string` The sql query string. +* sql - `required` `string` The text of sql statement. * offset - `optional` `int` Query offset. If offset is set in sql, curIndex will be ignored. * limit - `optional` `int` Query limit. If limit is set in sql, perPage will be ignored. -* acceptPartial - `optional` `bool` Whether accept a partial result or not, default be "true" to avoid a big scan on HBase. Set to "false" for production use. +* acceptPartial - `optional` `bool` Whether accept a partial result or not, default be "false". Set to "false" for production use. * project - `optional` `string` Project to perform query. Default value is 'DEFAULT'. -``` +#### Request Sample + +```sh { "sql":"select * from TEST_KYLIN_FACT", "offset":0, @@ -98,9 +103,19 @@ Authorization:Basic {data} } ``` +#### Response Body +* columnMetas - Column metadata information of result set. +* results - Data set of result. +* cube - Cube used for this query. +* affectedRowCount - Count of affected row by this sql statement. +* isException - Whether this response is an exception. +* ExceptionMessage - Message content of the exception. +* Duration - Time cost of this query +* Partial - Whether the response is a partial result or not. Decided by `acceptPartial` of request. + #### Response Sample -``` +```sh { "columnMetas":[ { @@ -181,8 +196,6 @@ Authorization:Basic {data} } ``` -*** - ## List queryable tables `GET /tables_and_columns` @@ -265,10 +278,10 @@ Authorization:Basic {data} `GET /cubes` #### Request Parameters -* cubeName - `optional` `string` Cube name to find. -* projectName - `optional` `string` project name. * offset - `required` `int` Offset used by pagination * limit - `required` `int ` Cubes per page. +* cubeName - `optional` `string` Keyword for cube names. To find cubes whose name contains this keyword. +* projectName - `optional` `string` Project name. #### Response Sample ```sh @@ -298,9 +311,9 @@ Authorization:Basic {data} #### Path Variable * cubeName - `required` `string` Cube name to find. - ## Get cube descriptor `GET /cube_desc/{cubeName}` +Get descriptor for specified cube instance. #### Path Variable * cubeName - `required` `string` Cube name. @@ -563,7 +576,7 @@ Authorization:Basic {data} `GET /model/{modelName}` #### Path Variable -* modelName - `required` `string` Data model name, by default it should be the same as cube name. +* modelName - `required` `string` Data model name, by default it should be the same with cube name. #### Response Sample ```sh @@ -685,27 +698,6 @@ Authorization:Basic {data} } ``` - -## Disable Cube -`PUT /cubes/{cubeName}/disable` - -#### Path variable -* cubeName - `required` `string` Cube name. - -#### Response Sample -(Same as "Enable Cube") - - -## Purge Cube -`PUT /cubes/{cubeName}/purge` - -#### Path variable -* cubeName - `required` `string` Cube name. - -#### Response Sample -(Same as "Enable Cube") - - ## Enable Cube `PUT /cubes/{cubeName}/enable` @@ -760,11 +752,31 @@ Authorization:Basic {data} } ``` +## Disable Cube +`PUT /cubes/{cubeName}/disable` + +#### Path variable +* cubeName - `required` `string` Cube name. + +#### Response Sample +(Same as "Enable Cube") + +## Purge Cube +`PUT /cubes/{cubeName}/purge` + +#### Path variable +* cubeName - `required` `string` Cube name. + +#### Response Sample +(Same as "Enable Cube") + +*** + ## Resume Job `PUT /jobs/{jobId}/resume` #### Path variable -* jobId- `required` `string` Job id. +* jobId - `required` `string` Job id. #### Response Sample ``` @@ -832,7 +844,7 @@ Authorization:Basic {data} `PUT /jobs/{jobId}/cancel` #### Path variable -* jobId- `required` `string` Job id. +* jobId - `required` `string` Job id. #### Response Sample (Same as "Resume job") @@ -851,6 +863,7 @@ Authorization:Basic {data} } ``` +*** ## Get Hive Table `GET /tables/{tableName}` @@ -962,18 +975,16 @@ Authorization:Basic {data} totalFileSize: "46069", outputformat: "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat" } -} + } ] ``` ## Load Hive Tables `POST /tables/{tables}/{project}` - #### Request Parameters -* tables- `required` `string` table names you want to load from hive, separated with comma. -* project- `required` `String` the project which the tables will be loaded into. - +* tables - `required` `string` table names you want to load from hive, separated with comma. +* project - `required` `String` the project which the tables will be loaded into. #### Response Sample ``` @@ -983,6 +994,7 @@ Authorization:Basic {data} } ``` +*** ## Wipe cache `GET /cache/{type}/{name}/{action}` http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_docs/howto/howto_use_restapi_in_js.md ---------------------------------------------------------------------- diff --git a/website/_docs/howto/howto_use_restapi_in_js.md b/website/_docs/howto/howto_use_restapi_in_js.md index d9fa273..f41b3c5 100644 --- a/website/_docs/howto/howto_use_restapi_in_js.md +++ b/website/_docs/howto/howto_use_restapi_in_js.md @@ -3,12 +3,12 @@ layout: docs title: How to Use Restful API in Javascript categories: howto permalink: /docs/howto/howto_use_restapi_in_js.html -version: v1.0 +version: v1.2 since: v0.7.1 --- -Kypin securicty authorization is based on basic access authorization, so when you want to use API in your javascript,you need to involve the authorization info in http headers. +Kylin security is based on basic access authorization, if you want to use API in your javascript, you need to add authorization info in http headers. -## Here is a demo show how to use Kylin Query API. +## Example on Query API. ``` $.ajaxSetup({ headers: { 'Authorization': "Basic eWFu**********X***ZA==", 'Content-Type': 'application/json;charset=utf-8' } // use your own authorization code here @@ -28,14 +28,13 @@ $.ajaxSetup({ ``` +## Keypoints +1. add basic access authorization info in http headers. +2. use right ajax type and data synax. -For what is basic access authorization ,click here http://en.wikipedia.org/wiki/Basic_access_authentication - -## Keypoint: -1. add basic access authorization info in heders. -2. use right ajax type and right data synax - -How to generate your authorization code (download and import "jquery.base64.js" from https://github.com/yckart/jquery.base64.js) +## Basic access authorization +For what is basic access authorization, refer to [Wikipedia Page](http://en.wikipedia.org/wiki/Basic_access_authentication). +How to generate your authorization code (download and import "jquery.base64.js" from [https://github.com/yckart/jquery.base64.js](https://github.com/yckart/jquery.base64.js)). ``` var authorizationCode = $.base64('encode', 'NT_USERNAME' + ":" + 'NT_PASSWORD'); http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_docs/index.md ---------------------------------------------------------------------- diff --git a/website/_docs/index.md b/website/_docs/index.md index 74e61dc..e1cee70 100644 --- a/website/_docs/index.md +++ b/website/_docs/index.md @@ -26,7 +26,7 @@ Advanced Topics --- -#### REST API +#### REST APIs 1. [Kylin Restful API list](howto/howto_use_restapi.html) 2. [Build cube with Restful API](howto/howto_build_cube_with_restapi.html) http://git-wip-us.apache.org/repos/asf/kylin/blob/76397b67/website/_docs/install/hadoop_evn.md ---------------------------------------------------------------------- diff --git a/website/_docs/install/hadoop_evn.md b/website/_docs/install/hadoop_evn.md index 7e0c166..c67bb50 100644 --- a/website/_docs/install/hadoop_evn.md +++ b/website/_docs/install/hadoop_evn.md @@ -22,8 +22,8 @@ If you don't know how, here's a simple tutorial for hortonworks sanbox: Use ambari helps to launch hadoop: - ambari-agent start - ambari-server start +ambari-agent start +ambari-server start With both command successfully run you can go to ambari homepage at <http://your_sandbox_ip:8080> (user:admin,password:admin) to check everything's status. **By default hortonworks ambari disables Hbase, you'll need manually start the `Hbase` service at ambari homepage.**
