Notebooks Hub API

This section documents the functionality of Notebooks Hub API.

Notebooks Hub API is a Node.js application that provides a REST API for managing and interacting with the Notebooks Hub UI. It is built using the LoopBack framework. Notebooks Hub API controls external services, such as JupyterHub, Vault, and other similar services, through REST API calls. For more details on LoopBack, please refer to the LoopBack documentation

At the center on Notebooks Hub is the concept of Server - an application instance launched by JupyterHub and providing (i.e. JupyterLab, VSCode, etc). Notebooks Hub tracks useful metadata to the JupyterHub servers. For that end we use Templates - a set of metadata that describes a Server, which can be thought of as Server settings. Templates are used to create new Servers.

ServerData database model has the following properties:

  1. name - this is the server name that will be used in JupyterHub

  2. owner - the user under whose account the server will be created in JupyterHub

  3. templateData - templateData object used by this server

  4. status - one of the following: ‘stopped’, ‘starting’, ‘running’, ‘stopping’, based on the status of the server in JupyterHub

  5. _id - internal ID in the database

ServerController

Each Template may have multiple Servers associated with it (many-to-one relationship). This relationship is particularly important in the case of Featured and Quick Launch Templates as it enables users to quickly create and start multiple server instances based on the same configuration. This ensures consistency across environments and also provides scalability, as users can quickly deploy identical setups tailored to their needs without reconfiguring the Template each time.”

GET /authenticated

Verify the access to a protected route.

Status Codes:

  • 200 OK – Route is protected

GET /datasets

Get Datasets for a given user.

Query Parameters:

  • email (string)

Status Codes:

  • 200 OK – An array of Datasets

Response JSON Object:

  • []._id (string)

  • [].description (string)

  • [].group_read[] (string)

  • [].group_write[] (string)

  • [].name (string) – (required)

  • [].owner (string)

  • [].user_read[] (string)

  • [].user_write[] (string)

  • [].write_access (boolean)

POST /datasets

Create a new Dataset

This creates an empty directory on the file system.

Request JSON Object:

  • description (string)

  • group_read[] (string)

  • group_write[] (string)

  • name (string) – (required)

  • owner (string)

  • user_read[] (string)

  • user_write[] (string)

  • write_access (boolean)

Status Codes:
Response JSON Object:

  • _id (string)

  • description (string)

  • group_read[] (string)

  • group_write[] (string)

  • name (string) – (required)

  • owner (string)

  • user_read[] (string)

  • user_write[] (string)

  • write_access (boolean)

DELETE /datasets/{id}

Delete Dataset with given ID

Parameters:

  • id (string)

Query Parameters:

  • email (string)

Status Codes:
PATCH /datasets/{id}

Update Dataset with given ID

Parameters:

  • id (string)

Query Parameters:

  • email (string)

Request JSON Object:

  • description (string)

  • group_read[] (string)

  • group_write[] (string)

  • name (string)

  • user_read[] (string)

  • user_write[] (string)

Status Codes:
GET /healthcheck

Get application health status.

Check for a working JupyterHub connection, mounted folders, and working database connection.

Query Parameters:

  • email (string)

Status Codes:

  • 200 OK – Health status returned

PUT /initialize

Initialize a new JupyterHub user and set up their environment.

Query Parameters:

  • email (string)

Status Codes:
GET /modules

Get Modules for a given user.

Query Parameters:

  • email (string)

Status Codes:

  • 200 OK – An array of Modules

Response JSON Object:

  • []._id (string)

  • [].description (string)

  • [].featured (boolean)

  • [].group_read[] (string)

  • [].group_write[] (string)

  • [].luaModuleFile[].arguments[] (string)

  • [].luaModuleFile[].id (string)

  • [].name (string) – (required)

  • [].owner (string)

  • [].user_read[] (string)

  • [].user_write[] (string)

  • [].version (string) – (required)

  • [].write_access (boolean)

POST /modules

Create a new Module

This creates an empty binaries and a Lmod modulefile on the file system.

Request JSON Object:

  • description (string)

  • featured (boolean)

  • group_read[] (string)

  • group_write[] (string)

  • luaModuleFile[].arguments[] (string)

  • luaModuleFile[].id (string)

  • name (string) – (required)

  • owner (string)

  • user_read[] (string)

  • user_write[] (string)

  • version (string) – (required)

  • write_access (boolean)

Status Codes:
Response JSON Object:

  • _id (string)

  • description (string)

  • featured (boolean)

  • group_read[] (string)

  • group_write[] (string)

  • luaModuleFile[].arguments[] (string)

  • luaModuleFile[].id (string)

  • name (string) – (required)

  • owner (string)

  • user_read[] (string)

  • user_write[] (string)

  • version (string) – (required)

  • write_access (boolean)

DELETE /modules/{id}

Delete a Module with given ID

Parameters:

  • id (string)

Query Parameters:

  • email (string)

Status Codes:
PATCH /modules/{id}

Update Module with given ID

Parameters:

  • id (string)

Query Parameters:

  • email (string)

Request JSON Object:

  • description (string)

  • group_read[] (string)

  • group_write[] (string)

  • luaModuleFile[].arguments[] (string)

  • luaModuleFile[].id (string)

  • name (string)

  • user_read[] (string)

  • user_write[] (string)

  • version (string)

Status Codes:
DELETE /secret/{id}

Delete a Secret with a given ID

Parameters:

  • id (string)

Status Codes:
GET /secret/{id}

Get Secret with a given ID

Parameters:

  • id (string)

Status Codes:
PATCH /secret/{id}

Update a Secret with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • access[] (string)

  • description (string)

  • mount_path (string)

  • secretName (string)

Status Codes:
GET /secrets

Get Secrets. Optionally filter by owner, type and name

Query Parameters:

  • owner (string)

  • type (string)

  • name (string)

Status Codes:

  • 200 OK – An array of Secrets

Response JSON Object:

  • []._id (string)

  • [].access[] (string)

  • [].description (string)

  • [].engine (string) – (required)

  • [].mount_path (string)

  • [].owner (string) – (required)

  • [].secretName (string) – (required)

  • [].secret_path (string) – path to Secret in Vault directory (required)

  • [].type (string) – (required)

POST /secrets

Create a new Secret.

Request JSON Object:

  • access[] (string)

  • description (string)

  • mount_path (string)

  • owner (string) – (required)

  • secretName (string) – (required)

  • type (string) – (required)

Status Codes:

  • 200 OK – Secret POST success. Upload Secret Object.

GET /servers

Get Servers. Optionally filter by owner, type or name

Query Parameters:

  • owner (string)

  • type (string)

  • name (string)

Status Codes:

  • 200 OK – An array of Servers

Response JSON Object:

  • []._id (string)

  • [].owner (string) – (required)

  • [].status (string) – (required)

  • [].templateId (string) – (required)

POST /servers

Create a new Server and an associated Template.

Query Parameters:

  • owner (string)

Request JSON Object:

  • applicationType (string) – (required)

  • creator (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • tags[] (string)

  • type (string) – (required)

Status Codes:
Response JSON Object:

  • _id (string)

  • owner (string) – (required)

  • status (string) – (required)

  • templateId (string) – (required)

PUT /servers

Create a new Server based on an existing Template.

Query Parameters:

  • owner (string)

  • templateId (string)

Status Codes:
Response JSON Object:

  • _id (string)

  • owner (string) – (required)

  • status (string) – (required)

  • templateId (string) – (required)

DELETE /servers/{id}

Delete a Server with given ID. If the Server is running, it will be stopped first. It also deletes the associated Template if there is a one-to-one relationship between Server and Template.

Parameters:

  • id (string)

Status Codes:
GET /servers/{id}

Get Server with a given ID

Parameters:

  • id (string)

Status Codes:
Response JSON Object:

  • []._id (string)

  • [].owner (string) – (required)

  • [].status (string) – (required)

  • [].templateId (string) – (required)

GET /servers/{id}/share

Share a Server with given ID

Parameters:

  • id (string)

Status Codes:

  • 200 OK – Server sharing details

PUT /servers/{id}/start

Start a Server with given ID

Parameters:

  • id (string)

Status Codes:
PUT /servers/{id}/stop

Stop a Server with given ID

Parameters:

  • id (string)

Status Codes:
DELETE /template

Delete a Template with a given ID

Query Parameters:

  • templateId (string)

Status Codes:
PATCH /template

Update Template with given id.

Query Parameters:

  • templateId (string)

Request JSON Object:

  • applicationType (string)

  • creator (string)

  • datasets[] (string)

  • description (string)

  • featuredImage (string)

  • filePath (string)

  • hardware (string)

  • modules[] (string)

  • name (string)

  • public (boolean)

  • secrets[] (string)

  • tags[] (string)

Status Codes:
POST /template

Create a new Template.

Request JSON Object:

  • applicationType (string) – (required)

  • creator (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • tags[] (string)

  • type (string) – (required)

Status Codes:
Response JSON Object:

  • _id (string)

  • applicationType (string) – (required)

  • creator (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • serverName (string) – (required)

  • tags[] (string)

  • timestamp (string)

  • type (string) – (required)

GET /templates

Get Templates. Optionally filter by type or email

Query Parameters:

  • type (string)

  • email (string)

Status Codes:

  • 200 OK – An array of Templates

Response JSON Object:

  • []._id (string)

  • [].applicationType (string) – (required)

  • [].creator (string) – (required)

  • [].datasets[] (string)

  • [].description (string) – (required)

  • [].featuredImage (string)

  • [].filePath (string)

  • [].hardware (string) – (required)

  • [].modules[] (string)

  • [].name (string) – (required)

  • [].public (boolean) – (required)

  • [].secrets[] (string)

  • [].serverName (string) – (required)

  • [].tags[] (string)

  • [].timestamp (string)

  • [].type (string) – (required)

GET /templates/tags

Get Template tags sorted by frequency

Query Parameters:

  • type (string)

  • email (string)

Status Codes:

  • 200 OK – An array of sorted tag data

Response JSON Object:

  • []._id (string)

  • [].applicationType (string) – (required)

  • [].creator (string) – (required)

  • [].datasets[] (string)

  • [].description (string) – (required)

  • [].featuredImage (string)

  • [].filePath (string)

  • [].hardware (string) – (required)

  • [].modules[] (string)

  • [].name (string) – (required)

  • [].public (boolean) – (required)

  • [].secrets[] (string)

  • [].serverName (string) – (required)

  • [].tags[] (string)

  • [].timestamp (string)

  • [].type (string) – (required)

GET /version

Get API version.

Status Codes:
POST /volume/file

Create a new file in a specified directory.

Query Parameters:

  • email (string)

Request JSON Object:

  • content (string)

  • name (string)

  • path (string)

  • root (string)

  • type (string)

Status Codes:
Response JSON Object:

  • content (string)

  • name (string)

  • path (string)

  • root (string)

  • type (string)

GET /volume/files

Retrieve file data from a specified directory.

Query Parameters:

  • email (string)

  • root (string)

  • path (string)

Status Codes:

  • 200 OK – An array of file data

Response JSON Object:

  • [].name (string)

  • [].path (string)

  • [].root (string)

  • [].type (string)

GET /volume/hardware

Retrieve a list of hardware options.

Status Codes:

  • 200 OK – An array of hardware options

Response JSON Object:

  • [] (string)

GET /volume/lua

Retrieve a list of LUA file properties.

Status Codes:

  • 200 OK – An array of LUA file properties

Response JSON Object:

  • [] (string)

GET /whoami

Retrieve your username based on your JWT access token and session id.

Status Codes:

  • 200 OK – the logged in username