# zeppelin-api-interface

> A JS API interface for REST/WebSocket endpoints of Apache Zeppelin

Latest version **1.5.1** (published 2019-04-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install zeppelin-api-interface
pnpm add zeppelin-api-interface
yarn add zeppelin-api-interface
bun add zeppelin-api-interface
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.1 |
| Published | 2019-04-05 |
| First published | 2017-10-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 48.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | caesarsol |

## Links

- npm: https://www.npmjs.com/package/zeppelin-api-interface
- Repository: https://bitbucket.org/accurat/zeppelin-api-interface
- Homepage: https://bitbucket.org/accurat/zeppelin-api-interface#readme
- npm.io page: https://npm.io/package/zeppelin-api-interface

## Dependencies (3)

- [url-join](https://npm.io/package/url-join.md) ^2.0.1
- [map-values](https://npm.io/package/map-values.md) ^1.0.1
- [isomorphic-fetch](https://npm.io/package/isomorphic-fetch.md) ^2.2.1

## Recent versions

- 1.5.1 (latest) — 2019-04-05
- 1.5.0 — 2019-04-05
- 1.4.0 — 2017-12-06
- 1.3.0 — 2017-10-20

## README

# Zeppelin API interface

## WebSocket Endpoint

Anonymous:

```js
import { buildZeppelinWebsocket } from 'zeppelin-api-interface'
const zeppelinHost = `localhost:8000`
const wsEndpoint = `ws://${zeppelinHost}/ws`
const socket = buildZeppelinWebsocket(wsEndpoint)
// ...
```

With login:

```js
import { setHost, User, buildZeppelinWebsocket } from 'zeppelin-api-interface'
const zeppelinHost = `localhost:8000`
const wsEndpoint = `ws://${zeppelinHost}/ws`
const httpHost = `http://${zeppelinHost}/`
setHost(httpHost)
User.login(user, password).then(({ success, error, response }) => {
  if (!success) window.alert("Login is not needed")
  const credentials = response.body // { principal: '...', ticket: '...', roles: '[...]' }
  const socket = buildZeppelinWebsocket(wsEndpoint, credentials)
  // ...
})
```

Then:

```js
socket.on('error', err => {
  console.error(`Error in WebSocket connection: ${JSON.stringify(err)}`)
})

socket.on('open', () => {
  socket.getNotebookList() // The initial socket command
})

socket.on('send', (event, message) => {
  if (message.op === 'PING') return
  console.log('\uD83D\uDC5F <<', message.op, message.data || '')
})

socket.on('message', (event, message) => {
  console.log('\uD83D\uDC5F >>', message.op, message.data || '')

  actOnSocketMessage(message)
})
```

In `actOnSocketMessage` you would manage the entire [list of socket messages](https://github.com/apache/zeppelin/blob/branch-0.7/zeppelin-zengine/src/main/java/org/apache/zeppelin/notebook/socket/Message.java), while the list of possible `socket` commands is [here](src/zeppelin-websocket.js#zeppelin-websocket.js-38).

## REST Endpoints

Every function returns a promise of `Object { success: boolean, response: Object | string, error?: string }`.

- `success`: the HTTP JSON call was successful or not
- `response`: the JSON in case of success, the body text in case of error
- `error`: the HTTP error returned from the server

The hostname can be set once, with `setHost`.

```js
import { Notebook, Paragraph, setHost } from 'zeppelin-api-interface'

setHost('http://localhost:8080/') // In production it should be left to empty string
```

### Notebooks

- Auto-documented source: [index.js](src/index.js)
- Zeppelin API Doc: [Notebook API](http://zeppelin.apache.org/docs/0.7.1/rest-api/rest-notebook.html#note-operations)

```js
// List all notebooks
Notebook.list().then(({ success, response, error }) => {
  if (!success) return console.error(error) // Remember to always handle the error in some way

  const notebooks = response.body
  notebooks.forEach(notebook => {
    console.log(`- Notebook name: "${notebook.name}" (ID: ${notebook.id})`))
  })
})

// Create a notebook
Notebook.create('Test notebook 1').then(({ success, response, error }) => {
  if (!success) return console.error(error) // Remember to always handle the error in some way

  const createdNotebookId = response.body
  console.log(`Created notebook with ID: ${createdNotebookId}`)
})
```

If using Babel ES2017 or Node 7.6+, you can also use `async/await` syntax:

```js
async function doApiCall() {
  const { success, response, error } = await Notebook.create('Test notebook 2')
  if (!success) return console.error(error) // Remember to always handle the error in some way
  const createdNotebookId = response.body
  console.log(`Created notebook with ID: ${createdNotebookId}`)
}
```

### Paragraphs

- Auto-documented source: [index.js](src/index.js)
- Zeppelin API Doc: [Paragraph API](http://zeppelin.apache.org/docs/0.7.1/rest-api/rest-notebook.html#paragraph-operations)

The methods are the same as in `Notebook`, with the exception of an additional `notebookId` parameter in first position.

The only difference is the `Notebook.create` method, which accepts an Object with the data for creation:
```js
Paragraph.create(createdNotebookId, {
  title: 'Test paragraph 1',
  text: `%spark
    println("Paragraph test run")
  `
}).then(/* ... */)
```

### Running Paragraphs

- Auto-documented source: [index.js](src/index.js)
- Zeppelin API Doc: [Paragraph Run](http://zeppelin.apache.org/docs/0.7.1/rest-api/rest-notebook.html#run-a-paragraph-asynchronously)

The `ParagraphJobs` namespace have methods to `run`, `runSync`, `stop`, `stat` (get status).

The `runSync` function does a run in a single HTTP call:

```js
ParagraphJobs.runSync(createdNotebookId, createdParagraphId).then(({ success, response, error }) => {
  if (!success) return console.error(error) // Remember to always handle the error in some way

  const result = response.body // is { code: 'SUCCESS', msg: [ { type: 'TEXT', data: 'Paragraph test run\n' } ] }
})
```

- `response.body.code` contains the paragraph `text` compilation status.
- `response.body.msg` has a representation of the result.

For longer data computations, an asynchronous `run` call will be necessary.
The implementation is there, but not yet tested.

## Development

To release a new version run `yarn release`, it will guide to a new release.

---
_Source: https://npm.io/package/zeppelin-api-interface · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._