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
DuyHai DOAN 7e2a1b5d4f [ZEPPELIN-699] Add new synchronous paragraph run REST API 
### What is this PR for?
Right now, when calling the REST API `http://<ip>:<port>/api/notebook/job/<note_id>/<paragraph_id>` Zeppelin always returns **OK** as shown by this source code: https://github.com/apache/incubator-zeppelin/blob/master/zeppelin-server/src/main/java/org/apache/zeppelin/rest/NotebookRestApi.java#L477

This ticket will update the behavior so that Zeppelin also return the result of the paragraph execution

### What type of PR is it?
[Improvement]

### Todos
* [ ] - Code Review
* [ ] - Simple Test

### Is there a relevant Jira issue?
**[ZEPPELIN-699]**

### How should this be tested?
* `git fetch origin pull/746/head:ParagraphExecutionRESTAPI`
* `git checkout ParagraphExecutionRESTAPI`
* `mvn clean package -DskipTests`
* `bin/zeppelin-daemon.sh restart`
* Create a new note
* In the first paragraph, put the following code

```scala
%sh

echo "Current time = "`date +"%T"
```

* Retrieve the current note id in the URL
* Retrieve the current paragraph id
* Use a REST Client like **[POSTman]** to create a HTTP POST query `http://<ip>:<port>/api/notebook/run/<note_id>/<paragraph_id>`
* You should receive something similar as follow for answer

```
{
    "status": "OK",
    "body": {
        "code": "SUCCESS",
        "type": "TEXT",
        "msg": "Current time = 16:14:18\n"
    }
}
```

### Screenshots (if appropriate)
![zeppelin_synchronous_rest_api](https://cloud.githubusercontent.com/assets/1532977/15748069/b4a26a46-28dd-11e6-8f51-aa13ddba3f1c.gif)

API Documentation update

**Existing asynchronous API**
![image](https://cloud.githubusercontent.com/assets/1532977/15773274/5b508cae-2976-11e6-9e52-14d8b7e7828e.png)

**New synchronous API**
![image](https://cloud.githubusercontent.com/assets/1532977/15773309/84965a94-2976-11e6-9719-81d8b555c3c4.png)

### Questions:
* Does the licenses files need update? --> **No**
* Is there breaking changes for older versions? --> **No**
* Does this needs documentation? --> **Yes**

[ZEPPELIN-699]: https://issues.apache.org/jira/browse/ZEPPELIN-699
[POSTman]: https://www.getpostman.com/

Author: DuyHai DOAN <doanduyhai@gmail.com>

Closes #746 from doanduyhai/ZEPPELIN-699 and squashes the following commits:

fb0570c [DuyHai DOAN] [ZEPPELIN-699] Update Notebook REST API documentation
8367acf [DuyHai DOAN] [ZEPPELIN-699] Add new synchronous paragraph run REST API
2016-08-31 23:56:39 -07:00

24 KiB
Raw Blame History

layout title description group
page Apache Zeppelin Notebook REST API This page contains Apache Zeppelin Notebook REST API information. 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.
If you can not find Notebook id 404 returns. If there is a problem with the interpreter returns a 412 error.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]```
Success code 200
Fail code 404 or 412
sample JSON response 
{"status": "OK"}
sample JSON error response 
           {
             "status": "NOT_FOUND",
             "message": "note not found."
           }
         

           {
             "status": "PRECONDITION_FAILED",
             "message": "paragraph_1469771130099_-278315611 Not selected or Invalid Interpreter bind"
           }

### 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"
    }
  ]
}

### Get the status of a single paragraph
Description This ```GET``` method gets the status of a single paragraph by the given notebook and paragraph 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]/[paragraphId]```
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"
    }
}

### Run a paragraph asynchronously
Description This ```POST``` method runs the paragraph asynchronously by given notebook and paragraph id. This API always return SUCCESS even if the execution of the paragraph fails later because the API is asynchronous
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"}

### Run a paragraph synchronously
Description This ```POST``` method runs the paragraph synchronously by given notebook and paragraph id. This API can return SUCCESS or ERROR depending on the outcome of the paragraph execution
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"}
sample JSON error 
{
   "status": "INTERNAL\_SERVER\_ERROR",
   "body": {
       "code": "ERROR",
       "type": "TEXT",
       "msg": "bash: -c: line 0: unexpected EOF while looking for matching ``'\nbash: -c: line 1: syntax error: unexpected end of file\nExitValue: 2"
   }
}

### 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"
}