REST API

jupyter_starters adds two routes to the Notebook server, which are primarily consumed by the @deathbeds/jupyterlab-starters JupyterLab extension.

Starter List

GET http://localhost:8888/starters

Returns a named map of starters, as loaded via traitlets. For example, the demo starters:

Show code cell source Hide code cell source

import json
import pathlib

import IPython

from jupyter_starters.handlers import VERSION

HERE = pathlib.Path.cwd()
starters = json.loads((HERE.parent.parent / "jupyter_server_config.json").read_text())[
    "StarterManager"
]["extra_starters"]
IPython.display.Markdown(
    f"""```json
{json.dumps({
    "version": VERSION,
    "starters": starters
}, indent=2, sort_keys=True) }
```"""
)

{
  "starters": {
    "multi-stage-notebook": {
      "description": "Build a directory one file at a time",
      "label": "Multi-Stage Starter Notebook",
      "src": "./examples/Multi-Stage Starter Notebook.ipynb",
      "type": "notebook"
    },
    "notebook-starter": {
      "description": "A notebook that is also a starter",
      "label": "Starter Notebook",
      "src": "./examples/Starter Notebook.ipynb",
      "type": "notebook"
    },
    "whitepaper-multiple": {
      "description": "Some reusable notebooks for proposing research",
      "icon": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 48 48'><g class='jp-icon-contrast1' fill='#ccc'><circle cx='24' cy='24' r='24'/></g></svg>",
      "label": "Whitepaper Folder",
      "src": "examples/whitepaper-multiple",
      "type": "copy"
    },
    "whitepaper-named": {
      "description": "A renamed whitepaper",
      "dest": "{% now 'local' %} {{ dest }} Whitepaper.ipynb",
      "icon": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><g class='jp-icon-contrast3' fill='#ccc'><rect width='100' height='100'/></g></svg>",
      "label": "Named Whitepaper",
      "schema": {
        "description": "> A whitepaper that already has a name, based on the [Heilmeier Catechism](https://www.darpa.mil/work-with-us/heilmeier-catechism).",
        "properties": {
          "dest": {
            "default": "Unimagined",
            "description": "the _topic_ of the whitepaper",
            "title": "## Topic",
            "type": "string"
          }
        },
        "required": [
          "dest"
        ],
        "title": "# A Named whitepaper",
        "type": "object"
      },
      "src": "examples/whitepaper-single.ipynb",
      "type": "copy",
      "uiSchema": {
        "dest": {
          "ui:autofocus": true,
          "ui:help": "keep it short and simple: it will go in $1$ file named: `<topic> Whitepaper.ipynb`"
        }
      }
    },
    "whitepaper-single": {
      "description": "A reusable notebook for proposing research",
      "label": "Whitepaper Notebook",
      "src": "examples/whitepaper-single.ipynb",
      "type": "copy"
    }
  },
  "version": "3"
}

Starter

POST http://localhost:8888/starters/{:starter-name}/{:api-path}

Returns a start response, e.g.

{
  "body": null,
  "name": "whitepaper-single",
  "path": "whitepaper-single.ipynb",
  "starter": {
    "description": "A reusable notebook for proposing research",
    "label": "Whitepaper Notebook",
    "src": "examples/whitepaper-single.ipynb",
    "type": "copy"
  },
  "status": "done"
}