API docs by Redocly

Noteburst (0.1.dev1+gd0cc6a5)

Download OpenAPI specification:Download

Noteburst is a Rubin Science Platform API service for Jupyter Notebook execution.

Noteburst runs notebooks on a pool of JupyterLab (Nublado) instances that it operates. This means that your notebooks can use any feature expected in a regular nublado session, such as pre-installed software and Python packages, datasets, and other storage.

For more information about Noteburst's design and architecture, see SQR-065: Design of Noteburst: a programmatic JupyterLab notebook execution service for the Rubin Science Platform. Noteburst is developed at https://github.com/lsst-sqre/noteburst by Rubin Observatory's SQuaRE team.

Internal application metadata

Return metadata about the running application. Can also be used as a health check. This route is not exposed outside the cluster and therefore cannot be used by external clients.

Responses

Response samples

Content type
application/json
{}

Application metadata

Discover metadata about the application.

Responses

Response samples

Content type
application/json
{}

v1

Submit a notebook for execution

Submits a notebook for execution. The notebook is executed asynchronously via a pool of JupyterLab (Nublado) instances.

Configuring how the notebook is run

The JupyterLab kernel can be set via the optional kernel_name field. The default kernel is LSST, which is a Python 3 kernel that includes the full Rubin Python environment (rubinenv).

Note that you cannot specify some aspects of the JupyterLab pod that the notebook is run on:

  • The user identity (a generic account is used)
  • The Nublado version
  • The machine size

Getting the notebook status and result

The JSON response body includes a self_url field (the same value is also available in the Location response header). You can send a GET request to this URL to get metadata about the execution job and (if available) the notebook (ipynb) result. See GET /v1/notebooks/{job_id} for more information.

Request Body schema: application/json
required
The contents of a Jupyter notebook (string) or The contents of a Jupyter notebook (object) (The contents of a Jupyter notebook)

If a string, the content is parsed as JSON. Alternatively, the content can be submitted pre-parsed as an object.

kernel_name
string (The name of the Jupyter kernel the kernel is executed with)
Default: "LSST"

The default kernel, LSST, contains the full Rubin Python environment, rubinenv, which includes the LSST Science Pipelines.

timeout
string <duration> (HumanTimedelta)

The timeout can either be written as a number in seconds or as a human-readable duration string. For example, '5m' is 5 minutes, '1h' is 1 hour, '1d' is 1 day. If the notebook execution does not complete within this time, the job is marked as failed.

enable_retry
boolean (Enable retries on failures)
Default: true

If true (default), noteburst will retry notebook execution if the notebook fails, with an increasing back-off time between tries. This is useful for dealing with transient issues. However, if you are using Noteburst for continuous integration of notebooks, disabling retries provides faster feedback.

Responses

Request samples

Content type
application/json
{
  • "ipynb": "string",
  • "kernel_name": "LSST",
  • "timeout": "string",
  • "enable_retry": true
}

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "kernel_name": "LSST",
  • "enqueue_time": "2019-08-24T14:15:22Z",
  • "status": "deferred",
  • "self_url": "http://example.com",
  • "source": "string",
  • "start_time": "2019-08-24T14:15:22Z",
  • "finish_time": "2019-08-24T14:15:22Z",
  • "success": true,
  • "error": {
    },
  • "ipynb": "string",
  • "ipynb_error": {
    },
  • "timeout": 0
}

Get information about a notebook execution job

Provides information about a notebook execution job, and the result (if available).

Information from a completed notebook

Many response fields are only included when the result is available (the status field is complete):

  • ipynb (the JSON-included executed Jupyter notebook)
  • start_time
  • finish_time
  • success

If you do not require these fields, regardless of the status, you can set the result=false URL query parameter. This speeds up the response slightly.

Toggling inclusion of the source notebook

If you require the notebook that was originally submitted, set the URL query parameter source=true.

path Parameters
job_id
required
string (Job Id)
query Parameters
source
boolean (Include source ipynb)
Default: false

If set to true, the source field will include the JSON-encoded content of the source ipynb notebook.

result
boolean (Include the result)
Default: true

If set to true and the notebook run is complete, the response includes the executed notebook and metadata about the run.

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "kernel_name": "LSST",
  • "enqueue_time": "2019-08-24T14:15:22Z",
  • "status": "deferred",
  • "self_url": "http://example.com",
  • "source": "string",
  • "start_time": "2019-08-24T14:15:22Z",
  • "finish_time": "2019-08-24T14:15:22Z",
  • "success": true,
  • "error": {
    },
  • "ipynb": "string",
  • "ipynb_error": {
    },
  • "timeout": 0
}