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
Jungtaek Lim f78d3096e0 ZEPPELIN-528 REST API: add "progress" to 'get notebook job' API 
### What is this PR for?

To add 'progress' to 'get notebook job' REST API.
All paragraphs which status is 'running' will include 'progress' to their job status.

### What type of PR is it?

Improvement

### Todos

### Is there a relevant Jira issue?

https://issues.apache.org/jira/browse/ZEPPELIN-528

### How should this be tested?

1. Run a notebook or paragraph which takes some times. Paragraph which could show progress (%) would be more appreciated. Confirm that its status is 'RUNNING'.
2. Call ```http://<zeppelin host>:<zeppelin port>/api/notebook/job/<notebook id>``` to see if it has 'progress' field in JSON.

### Screenshots (if appropriate)

![notebook-2b68v95jm](https://cloud.githubusercontent.com/assets/1317309/11949192/cf176d8e-a8bf-11e5-9bb2-8f4dbd1666c8.png)
![notebook-job-api-result-2b68v95jm](https://cloud.githubusercontent.com/assets/1317309/11949191/cf16f7e6-a8bf-11e5-825b-97c6fa227d05.png)

### Questions:
* Does the licenses files need update? (No)
* Is there breaking changes for older versions? (No)
* Does this needs documentation? (Yes or no. Output of the JSON format could be updated, but it could be treated as not mandatory.)

Author: Jungtaek Lim <kabhwan@gmail.com>

Closes #563 from HeartSaVioR/ZEPPELIN-528 and squashes the following commits:

dc86b01 [Jungtaek Lim] ZEPPELIN-528 Add UT to get notebook job (especially 'progress' field)
69a58ab [Jungtaek Lim] Merge branch 'master' into ZEPPELIN-528
31a8e88 [Jungtaek Lim] ZEPPELIN-528 Explain new field 'progress' to JSON output
2597ebf [Jungtaek Lim] ZEPPELIN-528 Add 'progress' to paragraph information when running
2015-12-25 01:00:07 +09:00

14 KiB
Raw Blame History

layout title description group
page Notebook REST API rest-api

{% include JB/setup %}

Zeppelin REST API

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 zeppelin REST APIs receive or return JSON objects, it is recommended for you to install some JSON viewer such as JSONView

If you work with zeppelin and find a need for an additional REST API please file an issue or send us mail


### Notebook REST API list

Notebooks REST API supports the following operations: List, Create, Get, Delete, Clone, Run as detailed in the following table

List 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 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 notebook
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 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 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 notebook job
Description This ```POST``` method runs all paragraph 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 notebook job
Description This ```DELETE``` method stops all paragraph 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 notebook job
Description This ```GET``` method gets all paragraph status 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 paragraph job
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 paragraph job
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":""}]}