Skip to content

Latest commit

 

History

History
1818 lines (1715 loc) · 36.2 KB

notebook.md

File metadata and controls

1818 lines (1715 loc) · 36.2 KB
layout title description group
page
Apache Zeppelin Notebook REST API
This page contains Apache Zeppelin Notebook REST API information.
usage/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.

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

Note operations

List of the notes

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

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

### Get the status of all paragraphs
Description This ```GET``` method gets the status of all paragraphs by the given note 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/[noteId]```
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 an existing note information
Description This ```GET``` method retrieves an existing note's information using the given id. The body field of the returned JSON contain information about paragraphs in the note.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]```
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",
        "results": {
          "code": "SUCCESS",
          "msg": [
            {
              "type": "TABLE",
              "data": "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 note
Description This ```DELETE``` method deletes a note by the given note id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK","message": ""}

### Clone a note
Description This ```POST``` method clones a note by the given id and create a new note using the given name or default name if none given. If what you want to copy is a certain version of note, you need to specify the revisionId. The body field of the returned JSON contains the new note id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]```
Success code 200
Fail code 500
sample JSON input 
{
  "name": "name of new note",
  "revisionId": "revisionId of note to be copied (optional)"
}
sample JSON response 
{
  "status": "OK",
  "message": "",
  "body": "2AZPHY918"
}

### Rename a note
Description This ```PUT``` method renames a note by the given id using the given name.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/rename```
Success code 200
Bad Request code 400
Fail code 500
sample JSON input 
{"name": "new name of a note"}
sample JSON response 
{"status":"OK"}

### Export a note
Description This ```GET``` method exports a note by the given id and gernerates a JSON
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/export/[noteId]```
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 note
Description This ```POST``` method imports a note from the note 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": "OK",
  "message": "",
  "body": "2AZPHY918"
}

Run all paragraphs

Description This ```POST``` method runs all paragraphs in the given note id.
If you can not find Note id 404 returns. If there is a problem with the interpreter returns a 412 error.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[noteId]```
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 note id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[noteId]```
Success code 200
Fail code 500
sample JSON response 
{"status":"OK"}

### Clear all paragraph result
Description This ```PUT``` method clear all paragraph results from note of given id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/clear```
Success code 200
Forbidden code 401
Not Found code 404
Fail code 500
sample JSON response 
{"status": "OK"}

Paragraph operations


### 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/[noteId]/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 input (providing paragraph config) 
{
  "title": "paragraph title2",
  "text": "paragraph text2",
  "config": {
    "title": true,
    "colWidth": 6.0,
    "results": [
      {
        "graph": {
          "mode": "pieChart",
          "optionOpen": true
        }
      }
    ]
  }
}
sample JSON response 
{
  "status": "OK",
  "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/[noteId]/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",
    "results": {
      "code": "SUCCESS",
      "msg": [
        {
           "type": "TEXT",
           "data": "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
  }
}

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

Update paragraph

Description This ```PUT``` method update paragraph contents using given id, e.g. {"text": "hello"}
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/paragraph/[paragraphId]```
Success code 200
Bad Request code 400
Forbidden code 403
Not Found code 404
Fail code 500
sample JSON input 
{
  "title": "Hello world",
  "text": "println(\"hello world\")"
}
sample JSON response 
{
  "status": "OK",
  "message": ""
}

### Update paragraph configuration
Description This ```PUT``` method update paragraph configuration using given id so that user can change paragraph setting such as graph type, show or hide editor/result and paragraph size, etc. You can update certain fields you want, for example you can update colWidth field only by sending request with payload {"colWidth": 12.0}.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/paragraph/[paragraphId]/config```
Success code 200
Bad Request code 400
Forbidden code 403
Not Found code 404
Fail code 500
sample JSON input 
{
  "colWidth": 6.0,
  "graph": {
    "mode": "lineChart",
    "height": 200.0,
    "optionOpen": false,
    "keys": [
      {
        "name": "age",
        "index": 0.0,
        "aggr": "sum"
      }
    ],
    "values": [
      {
        "name": "value",
        "index": 1.0,
        "aggr": "sum"
      }
    ],
    "groups": [],
    "scatter": {}
  },
  "editorHide": true,
  "editorMode": "ace/mode/markdown",
  "tableHide": false
}
sample JSON response 
{
  "status":"OK",
  "message":"",
  "body":{
    "text":"%sql \nselect age, count(1) value\nfrom bank \nwhere age \u003c 30 \ngroup by
 age \norder by age",
    "config":{
      "colWidth":6.0,
      "graph":{
        "mode":"lineChart",
        "height":200.0,
        "optionOpen":false,
        "keys":[
          {
            "name":"age",
            "index":0.0,
            "aggr":"sum"
          }
        ],
        "values":[
          {
            "name":"value",
            "index":1.0,
            "aggr":"sum"
          }
        ],
        "groups":[],
        "scatter":{}
      },
      "tableHide":false,
      "editorMode":"ace/mode/markdown",
      "editorHide":true
    },
    "settings":{
      "params":{},
      "forms":{}
    },
    "apps":[],
    "jobName":"paragraph_1423500782552_-1439281894",
    "id":"20150210-015302_1492795503",
    "results":{
      "code":"SUCCESS",
      "msg": [
        {
          "type":"TABLE",
          "data":"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
  }
}

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

### Run a paragraph asynchronously
Description This ```POST``` method runs the paragraph asynchronously by given note 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/[noteId]/[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 note",
  "params": {
    "formLabel1": "value1",
    "formLabel2": "value2"
  }
}
sample JSON response 
{"status": "OK"}

### Run a paragraph synchronously
Description This ```POST``` method runs the paragraph synchronously by given note 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/run/[noteId]/[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 note",
  "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 note and paragraph id.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[noteId]/[paragraphId]```
Success code 200
Fail code 500
sample JSON response 
{"status": "OK"}

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

### Full text search through the paragraphs in all notes
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": "<noteId>/paragraph/<paragraphId>",
      "name":"Note Name", 
      "snippet":"",
      "text":""
    }
  ]
}

Cron jobs


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

Remove Cron Job

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

Get Cron Job

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

Permission

Get a note permission information

Description This ```GET``` method gets a note authorization information.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/permissions```
Success code 200
Forbidden code 403
Fail code 500
sample JSON response 
{  
   "status":"OK",
   "message":"",
   "body":{  
      "readers":[  
         "user2"
      ],
      "owners":[  
         "user1"
      ],
      "runners":[
         "user2"
      ],
      "writers":[  
         "user2"
      ]
   }
}

### Set note permission
Description This ```PUT``` method set note authorization information.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/permissions```
Success code 200
Forbidden code 403
Fail code 500
sample JSON input 
{
  "readers": [
    "user1"
  ],
  "owners": [
    "user2"
  ],
  "runners":[
    "user2"
  ],
  "writers": [
    "user1"
  ]
}
sample JSON response 
{
  "status": "OK"
}

Version control

Get revisions of a note

Description This ```GET``` method gets the revisions of a note.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/revision```
Success code 200
Fail code 500
sample JSON response 
{
    "status": "OK",
    "body": [
        {
            "id": "f97ce5c7f076783023d33623ad52ca994277e5c1",
            "message": "first commit",
            "time": 1645712061
        },
        {
            "id": "e9b964bebdecec6a59efe085f97db4040ae333aa",
            "message": "second commit",
            "time": 1645693163
        }
    ]
}

### Save a revision for a note
Description This ```POST``` method saves a revision for a note.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/revision```
Success code 200
Bad Request code 400
Fail code 500
sample JSON input 
{
  "commitMessage": "first commit"
}
sample JSON response 
{
  "status": "OK",
  "message": "",
  "body": "6a5879218dfb797b013bcd24a594808045e34875"
}
### Get a revision of a note
Description This ```GET``` method gets a revision of a note.
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/revision/{revisionId}```
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",
        "results": {
          "code": "SUCCESS",
          "msg": [
            {
              "type": "TABLE",
              "data": "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": {}
  }
}
### Revert a note to a specified version
Description This ```PUT``` method reverts a note to a specified version
URL ```http://[zeppelin-server]:[zeppelin-port]/api/notebook/[noteId]/revision/{revisionId}```
Success code 200
Fail code 500
sample JSON response 
{
  "status": "OK"
}