Elgato_dark/zeppelin
1
0
Fork 0
mirror of https://github.com/apache/zeppelin synced 2026-05-24 09:38:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
zeppelin/docs/rest-api/rest-notebook.md
AhyoungRyu 5975125f18 [ZEPPELIN-1018] Apply auto "Table of Contents" generator to Zeppelin docs website 
### What is this PR for?
I added auto TOC(Table of Contents) generator for Zeppelin documentation website. TOC can help people looking through whole contents at a glance and finding what they want quickly.

I just added `<div id="toc"></div>`  to the each documentation header. [`toc`](https://github.com/apache/zeppelin/compare/master...AhyoungRyu:ZEPPELIN-1018?expand=1#diff-85af09fb498a5667ea455391533f945dR3)  recognize `<h2>` & `<h3>` as a title in the docs  and it automatically generate TOC. So I set a rule for this work. (I'll write this rule on `docs/CONTRIBUTING.md` or [docs/howtocontributewebsite](https://zeppelin.apache.org/docs/0.6.0-SNAPSHOT/development/howtocontributewebsite.html)).

```
# Level-1 Heading  <- Use only for the main title of the page
## Level-2 Heading <- Start with this one
### Level-3 heading <- Only use this one for child of Level-2

toc only recognize Level-2 & Level-3
```

Please see the below attached screenshot image.

### What type of PR is it?
Improvement & Documentation

### Todos
* [x] - Add TOC generator
* [x] - Apply TOC(`<div id="toc"></div>`) to every documentation and reorganize each headers(apply the above rule)
* [x] - Fix some broken code block in several docs
* [x] - Apply TOC to `r.md` (Currently R docs has some duplicated info since [this one](d5e87fb8ba) and [this one](7d6cc7e991) )
* [x] - Apply TOC to `install.md` after #1010 merged
* [x] - Apply TOC to `interpreterinstallation.md` after #1042 merged

### What is the Jira issue?
[ZEPPELIN-1018](https://issues.apache.org/jira/browse/ZEPPELIN-1018)

### How should this be tested?
1. Apply this patch and build `docs/` with [this guide](https://github.com/apache/zeppelin/tree/master/docs#build-documentation)
2.  Visit some docs page. Then you can see TOC in the header of page.

### Screenshots (if appropriate)
 - Automatically generated TOC in Spark interpreter docs page
<img width="831" alt="screen shot 2016-06-16 at 9 37 18 pm" src="https://cloud.githubusercontent.com/assets/10060731/16140902/945b9c7a-340a-11e6-91f3-b6174738bed0.png">

### Questions:
* Does the licenses files need update?
No. Actually I used [jekyll-table-of-contents#copyright](https://github.com/ghiculescu/jekyll-table-of-contents#copyright). But I don't need to add a license for this :)
* Is there breaking changes for older versions? No
* Does this needs documentation? Maybe

Author: AhyoungRyu <fbdkdud93@hanmail.net>

Closes #1031 from AhyoungRyu/ZEPPELIN-1018 and squashes the following commits:

e66397b [AhyoungRyu] Apply TOC to interpreterinstallation.md
009579b [AhyoungRyu] Add more info to 'What is the next?' in install.md
04cf501 [AhyoungRyu] Revert 'where to start' section
b7cbe5f [AhyoungRyu] Fix typo
cf0911c [AhyoungRyu] Rename license file
388f35a [AhyoungRyu] Add jekyll-table-of-contents license info
6394c70 [AhyoungRyu] Fix image path in python.md
d00e4b1 [AhyoungRyu] Move interpreter/screenshot/ -> asset/../img/docs-img/
3ffb383 [AhyoungRyu] Remove duplicated info in r.md & apply toc
a03ca99 [AhyoungRyu] Exclude toc.js from pom.xml
3fae7df [AhyoungRyu] Apply auto generated toc to install.md
d114a9d [AhyoungRyu] Address @felixcheung feedback
6a788fe [AhyoungRyu] Resize TOC tab indent
6760c00 [AhyoungRyu] Apply auto TOC to all of docs under docs/storage/
fbde57f [AhyoungRyu] Apply auto TOC to all of docs under docs/quickstart/
db76eb6 [AhyoungRyu] Apply auto TOC to all of docs under docs/install/
f35db47 [AhyoungRyu] Apply auto TOC to all of docs under docs/displaysystem/
b05365f [AhyoungRyu] Apply auto TOC to all of docs under docs/rest-api/
163691c [AhyoungRyu] Apply auto TOC to all of docs under docs/manual/
bef398e [AhyoungRyu] Apply auto TOC to all of docs under docs/development/
9c5f76b [AhyoungRyu] Apply auto TOC to all of docs under docs/interpreter/
587d4ba [AhyoungRyu] Apply auto TOC to all of docs under docs/security/
1f10b97 [AhyoungRyu] Change toc configuration
78dca9e [AhyoungRyu] Add toc.js for auto generating TOC
2016-06-25 22:57:44 -07:00

20 KiB
Raw Blame History

layout title description group
page Notebook REST API rest-api

{% include JB/setup %}

Apache Zeppelin Notebook REST API

Overview

Apache Zeppelin provides several REST APIs for interaction and remote activation of zeppelin functionality. All REST APIs are available starting with the following endpoint http://[zeppelin-server]:[zeppelin-port]/api. Note that Apache Zeppelin REST APIs receive or return JSON objects, it is recommended for you to install some JSON viewers such as JSONView.

If you work with Apache Zeppelin and find a need for an additional REST API, please file an issue or send us an email.

Notebook REST API List

Notebooks REST API supports the following operations: List, Create, Get, Delete, Clone, Run, Export, Import as detailed in the following tables.

List of the notebooks

Description This ```GET``` method lists the available notebooks on your server. Notebook JSON contains the ```name``` and ```id``` of all notebooks.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook```
Success code 200
Fail code 500
sample JSON response 
{
  "status": "OK",
  "message": "",
  "body": [
    {
      "name":"Homepage",
      "id":"2AV4WUEMK"
    },
    {
      "name":"Zeppelin Tutorial",
      "id":"2A94M5J1Z"
    }
  ]
}

### Create a new notebook
Description This ```POST``` method creates a new notebook using the given name or default name if none given. The body field of the returned JSON contains the new notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook```
Success code 201
Fail code 500
sample JSON input (without paragraphs) 
{"name": "name of new notebook"}
sample JSON input (with initial paragraphs) 
{
  "name": "name of new notebook",
  "paragraphs": [
    {
      "title": "paragraph title1",
      "text": "paragraph text1"
    },
    {
      "title": "paragraph title2",
      "text": "paragraph text2"
    }
  ]
}
sample JSON response 
{
  "status": "CREATED",
  "message": "",
  "body": "2AZPHY918"
}

### Get an existing notebook information
Description This ```GET``` method retrieves an existing notebook's information using the given id. The body field of the returned JSON contain information about paragraphs in the notebook.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{
  "status": "OK",
  "message": "",
  "body": {
    "paragraphs": [
      {
        "text": "%sql \nselect age, count(1) value\nfrom bank \nwhere age < 30 \ngroup by age \norder by age",
        "config": {
          "colWidth": 4,
          "graph": {
            "mode": "multiBarChart",
            "height": 300,
            "optionOpen": false,
            "keys": [
              {
                "name": "age",
                "index": 0,
                "aggr": "sum"
              }
            ],
            "values": [
              {
                "name": "value",
                "index": 1,
                "aggr": "sum"
              }
            ],
            "groups": [],
            "scatter": {
              "xAxis": {
                "name": "age",
                "index": 0,
                "aggr": "sum"
              },
              "yAxis": {
                "name": "value",
                "index": 1,
                "aggr": "sum"
              }
            }
          }
        },
        "settings": {
          "params": {},
          "forms": {}
        },
        "jobName": "paragraph\_1423500782552\_-1439281894",
        "id": "20150210-015302\_1492795503",
        "result": {
          "code": "SUCCESS",
          "type": "TABLE",
          "msg": "age\tvalue\n19\t4\n20\t3\n21\t7\n22\t9\n23\t20\n24\t24\n25\t44\n26\t77\n27\t94\n28\t103\n29\t97\n"
        },
        "dateCreated": "Feb 10, 2015 1:53:02 AM",
        "dateStarted": "Jul 3, 2015 1:43:17 PM",
        "dateFinished": "Jul 3, 2015 1:43:23 PM",
        "status": "FINISHED",
        "progressUpdateIntervalMs": 500
      }
    ],
    "name": "Zeppelin Tutorial",
    "id": "2A94M5J1Z",
    "angularObjects": {},
    "config": {
      "looknfeel": "default"
    },
    "info": {}
  }
}

### Delete a notebook
Description This ```DELETE``` method deletes a notebook by the given notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK","message": ""}

### Clone a notebook
Description This ```POST``` method clones a notebook by the given id and create a new notebook using the given name or default name if none given. The body field of the returned JSON contains the new notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]```
Success code 201
Fail code 500
sample JSON input 
{"name": "name of new notebook"}
sample JSON response 
{
  "status": "CREATED",
  "message": "",
  "body": "2AZPHY918"
}

### Run all paragraphs
Description This ```POST``` method runs all paragraphs in the given notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK"}

### Stop all paragraphs
Description This ```DELETE``` method stops all paragraphs in the given notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{"status":"OK"}

### Get the status of all paragraphs
Description This ```GET``` method gets the status of all paragraphs by the given notebook id. The body field of the returned JSON contains of the array that compose of the paragraph id, paragraph status, paragraph finish date, paragraph started date.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{
  "status": "OK",
  "body": [
    {
      "id":"20151121-212654\_766735423",
      "status":"FINISHED",
      "finished":"Tue Nov 24 14:21:40 KST 2015",
      "started":"Tue Nov 24 14:21:39 KST 2015"
    },
    {
      "progress":"1",
      "id":"20151121-212657\_730976687",
      "status":"RUNNING",
      "finished":"Tue Nov 24 14:21:35 KST 2015",
      "started":"Tue Nov 24 14:21:40 KST 2015"
    }
  ]
}

### Run a paragraph
Description This ```POST``` method runs the paragraph by given notebook and paragraph id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]/[paragraphId]```
Success code 200
Fail code 500
sample JSON input (optional, only needed when if you want to update dynamic form's value) 
{
  "name": "name of new notebook",
  "params": {
    "formLabel1": "value1",
    "formLabel2": "value2"
  }
}
sample JSON response 
{"status": "OK"}

### Stop a paragraph
Description This ```DELETE``` method stops the paragraph by given notebook and paragraph id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]/[paragraphId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK"}

### Add Cron Job
Description This ```POST``` method adds cron job by the given notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/cron/[notebookId]```
Success code 200
Fail code 500
sample JSON input 
{"cron": "cron expression of notebook"}
sample JSON response 
{"status": "OK"}

Remove Cron Job

Description This ```DELETE``` method removes cron job by the given notebook id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/cron/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK"}

Get Cron Job

Description This ```GET``` method gets cron job expression of given notebook id. The body field of the returned JSON contains the cron expression.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/cron/[notebookId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK", "body": "* * * * * ?"}

### Full text search through the paragraphs in all notebooks
Description ```GET``` request will return list of matching paragraphs
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/search?q=[query]```
Success code 200
Fail code 500
Sample JSON response 
{
  "status": "OK",
  "body": [
    {
      "id": "/paragraph/",
      "name":"Notebook Name", 
      "snippet":"",
      "text":""
    }
  ]
}

### Create a new paragraph
Description This ```POST``` method create a new paragraph using JSON payload. The body field of the returned JSON contain the new paragraph id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]/paragraph```
Success code 201
Fail code 500
sample JSON input (add to the last) 
{
  "title": "Paragraph insert revised",
  "text": "%spark\nprintln(\"Paragraph insert revised\")"
}
sample JSON input (add to specific index) 
{
  "title": "Paragraph insert revised",
  "text": "%spark\nprintln(\"Paragraph insert revised\")",
  "index": 0
}
sample JSON response 
{
  "status": "CREATED",
  "message": "",
  "body": "20151218-100330\_1754029574"
}

### Get a paragraph information
Description This ```GET``` method retrieves an existing paragraph's information using the given id. The body field of the returned JSON contain information about paragraph.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]/paragraph/[paragraphId]```
Success code 200
Fail code 500
sample JSON response 
{
  "status": "OK",
  "message": "",
  "body": {
    "title": "Paragraph2",
    "text": "%spark\n\nprintln(\"it's paragraph2\")",
    "dateUpdated": "Dec 18, 2015 7:33:54 AM",
    "config": {
      "colWidth": 12,
      "graph": {
        "mode": "table",
        "height": 300,
        "optionOpen": false,
        "keys": [],
        "values": [],
        "groups": [],
        "scatter": {}
      },
      "enabled": true,
      "title": true,
      "editorMode": "ace/mode/scala"
    },
    "settings": {
      "params": {},
      "forms": {}
    },
    "jobName": "paragraph\_1450391574392\_-1890856722",
    "id": "20151218-073254\_1105602047",
    "result": {
      "code": "SUCCESS",
      "type": "TEXT",
      "msg": "it's paragraph2\n"
    },
    "dateCreated": "Dec 18, 2015 7:32:54 AM",
    "dateStarted": "Dec 18, 2015 7:33:55 AM",
    "dateFinished": "Dec 18, 2015 7:33:55 AM",
    "status": "FINISHED",
    "progressUpdateIntervalMs": 500
  }
}

### Move a paragraph to the specific index
Description This ```POST``` method moves a paragraph to the specific index (order) from the notebook.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]/paragraph/[paragraphId]/move/[newIndex]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK","message": ""}

### Delete a paragraph
Description This ```DELETE``` method deletes a paragraph by the given notebook and paragraph id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[notebookId]/paragraph/[paragraphId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK","message": ""}

### Export a notebook
Description This ```GET``` method exports a notebook by the given id and gernerates a JSON
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/export/[notebookId]```
Success code 201
Fail code 500
sample JSON response 
{
  "paragraphs": [
    {
      "text": "%md This is my new paragraph in my new note",
      "dateUpdated": "Jan 8, 2016 4:49:38 PM",
      "config": {
        "enabled": true
      },
      "settings": {
        "params": {},
        "forms": {}
      },
      "jobName": "paragraph\_1452300578795\_1196072540",
      "id": "20160108-164938\_1685162144",
      "dateCreated": "Jan 8, 2016 4:49:38 PM",
      "status": "READY",
      "progressUpdateIntervalMs": 500
    }
  ],
  "name": "source note for export",
  "id": "2B82H3RR1",
  "angularObjects": {},
  "config": {},
  "info": {}
}

### Import a notebook
Description This ```POST``` method imports a notebook from the notebook JSON input
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/import```
Success code 201
Fail code 500
sample JSON input 
{
  "paragraphs": [
    {
      "text": "%md This is my new paragraph in my new note",
      "dateUpdated": "Jan 8, 2016 4:49:38 PM",
      "config": {
        "enabled": true
      },
      "settings": {
        "params": {},
        "forms": {}
      },
      "jobName": "paragraph\_1452300578795\_1196072540",
      "id": "20160108-164938\_1685162144",
      "dateCreated": "Jan 8, 2016 4:49:38 PM",
      "status": "READY",
      "progressUpdateIntervalMs": 500
    }
  ],
  "name": "source note for export",
  "id": "2B82H3RR1",
  "angularObjects": {},
  "config": {},
  "info": {}
}
sample JSON response 
{
  "status": "CREATED",
  "message": "",
  "body": "2AZPHY918"
}