Return-Path: X-Original-To: apmail-drill-commits-archive@www.apache.org Delivered-To: apmail-drill-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 7E41418187 for ; Wed, 25 Nov 2015 22:02:50 +0000 (UTC) Received: (qmail 63087 invoked by uid 500); 25 Nov 2015 22:02:50 -0000 Delivered-To: apmail-drill-commits-archive@drill.apache.org Received: (qmail 62978 invoked by uid 500); 25 Nov 2015 22:02:50 -0000 Mailing-List: contact commits-help@drill.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: commits@drill.apache.org Delivered-To: mailing list commits@drill.apache.org Received: (qmail 62473 invoked by uid 99); 25 Nov 2015 22:02:50 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 25 Nov 2015 22:02:50 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id E8046E0019; Wed, 25 Nov 2015 22:02:49 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: bridgetb@apache.org To: commits@drill.apache.org Date: Wed, 25 Nov 2015 22:03:01 -0000 Message-Id: <8a85d74066094b28b2191d1950d8abad@git.apache.org> In-Reply-To: <6b23d18928664538ae260ceb1af9fdb8@git.apache.org> References: <6b23d18928664538ae260ceb1af9fdb8@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [13/31] drill git commit: organize ala web console organize ala web console Project: http://git-wip-us.apache.org/repos/asf/drill/repo Commit: http://git-wip-us.apache.org/repos/asf/drill/commit/c02403d2 Tree: http://git-wip-us.apache.org/repos/asf/drill/tree/c02403d2 Diff: http://git-wip-us.apache.org/repos/asf/drill/diff/c02403d2 Branch: refs/heads/gh-pages Commit: c02403d2c6c4e6fc65f231fdf5d18db0c4316930 Parents: b38d8e7 Author: Kristine Hahn Authored: Fri Nov 20 15:53:33 2015 -0800 Committer: Kristine Hahn Committed: Wed Nov 25 10:13:42 2015 -0800 ---------------------------------------------------------------------- _docs/developer-information/009-rest-api.md | 235 ++++++++++++----------- 1 file changed, 126 insertions(+), 109 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/drill/blob/c02403d2/_docs/developer-information/009-rest-api.md ---------------------------------------------------------------------- diff --git a/_docs/developer-information/009-rest-api.md b/_docs/developer-information/009-rest-api.md index 1df2b87..6aece41 100644 --- a/_docs/developer-information/009-rest-api.md +++ b/_docs/developer-information/009-rest-api.md @@ -3,113 +3,95 @@ title: "REST API" parent: "Developer Information" --- -The Drill REST API provides methods you can call to programmatically perform the same functions available in the [Drill Web Console](/starting-the-web-console/). For example, you can run queries, perform storage plugin tasks, such as creating a storage plugin, obtain profiles of queries, and get current memory metrics. +The Drill REST API provides methods that perform the same functions as those in the [Drill Web Console](/starting-the-web-console/). For example, you can run queries, perform storage plugin tasks, such as creating a storage plugin, obtain profiles of queries, and get current memory metrics. -Drill REST API calls having a .json suffix output return a JSON response body. Generally, these commands return HTML when used without the .json suffix. +An HTTP request having a .json suffix output returns a JSON response body. Generally, when you drop the .json suffix from these commands, Drill returns HTML. -A Drill REST request connects to Drill using the familiar Web Console URI: +An HTTP request connects to Drill using the familiar Web Console URI: `http://:8047` -## Getting Started with the Drill REST API +## Getting Started -Before making REST requests, [start Drill]({{site.baseurl}}/docs/starting-drill-on-linux-and-mac-os-x). +Before making HTTP requests, [start Drill]({{site.baseurl}}/docs/starting-drill-on-linux-and-mac-os-x). Several examples in the document use the donuts.json file. To download this file, go to [Drill test resources](https://github.com/apache/drill/blob/master/exec/java-exec/src/test/resources) page, locate donuts.json in the list of files, and download it. When using cURL, use unicode \u0027 for the single quotation mark as shown in the Query example. -## Links to HTTP Methods - -The following short description of methods link to more information and examples: - -* [List information about system/session options]({{site.baseurl}}/docs/rest-api/#get-options-json) -* [Change the value or type of the named option]({{site.baseurl}}/docs/rest-api/#post-option-optionname) -* [Get the profiles of running and completed queries]({{site.baseurl}}/docs/rest-api/#get-profiles-json) -* [Get the profile of the query that has the given queryid]({{site.baseurl}}/docs/rest-api/#get-profiles-queryid-json) -* [Cancel the query that has the given queryid]({{site.baseurl}}/docs/rest-api/#get-profiles-cancel-queryid) -* [Submit a query and return results]({{site.baseurl}}/docs/rest-api/#post-query-json) -* [Get the list of storage plugin names and configurations]({{site.baseurl}}/docs/rest-api/#get-storage-json) -* [Get the definition of the named storage plugin]({{site.baseurl}}/docs/rest-api/#get-storage-name-json) -* [Enable or disable the named storage plugin]({{site.baseurl}}/docs/rest-api/#get-storage-name-enable-val) -* [Create or update a storage plugin configuration]({{site.baseurl}}/docs/rest-api/#post-storage-name-json) -* [Delete a storage plugin configuration]({{site.baseurl}}/docs/rest-api/#delete-storage-name-json) -* [Get Drillbit information, such as ports numbers]({{site.baseurl}}/drill/docs/rest-api/#get-stats-json) -* [Get the current memory metrics]({{site.baseurl}}/docs/rest-api/#get-status-metrics) -* [Get the status of threads]({{site.baseurl}}/docs/rest-api/#get-status-threads) +This documentation presents HTTP methods in the same order as functions appear in the Web Console: -## Options -These methods get and set system options. +[**Query**]({{site.baseurl}}/docs/rest-api/#query) ----------- +Submit a query and return results] -### GET /options.json +[**Profiles**](({{site.baseurl}}/docs/rest-api/#profiles)) -List the name, default, and data type of the system and session options. +* Get the profiles of running and completed queries +* Get the profile of the query that has the given queryid +* Cancel the query that has the given queryid -**Example** +[**Storage**]({{site.baseurl}}/docs/rest-api/#storage) -`curl http://localhost:8047/options.json` +* Get the list of storage plugin names and configurations +* Get the definition of the named storage plugin +* Enable or disable the named storage plugin +* Create or update a storage plugin configuration +* Delete a storage plugin configuration +* Get Drillbit information, such as ports numbers +* Get the current memory metrics -**Response Body** +[**Threads**](({{site.baseurl}}/docs/rest-api/#threads)) - [ { - "name" : "planner.broadcast_factor", - "value" : 1.0, - "type" : "SYSTEM", - "kind" : "DOUBLE" - }, +Get the status of threads - . . . +[**Options**]({{site.baseurl}}/docs/rest-api/#options) - { - "name" : "store.parquet.compression", - "value" : "snappy", - "type" : "SYSTEM", - "kind" : "STRING" - }, +* List information about system/session options +* Change the value or type of the named option - . . . - { - "name" : "exec.enable_union_type", - "value" : false, - "type" : "SYSTEM", - "kind" : "BOOLEAN" - } ] +## Query + +Using the query method, you can programmatically run queries. ---------- -### POST /option/{optionName} +### POST /query.json -Change the value or type of the named option. +Submit a query and return results. -**Parameter** +**Parameters** -optionName--The name of a [Drill system option]({{site.baseurl}}/docs/configuration-options-introduction/#system-options). +* queryType--SQL, PHYSICAL, or LOGICAL are valid types. Use only "SQL". Other types are for internal use only. +* query--A SQL query that runs in Drill. **Request Body** -Enclose option values of kind STRING in double quotation marks. - { - "name" : "