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 /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:

• 201 Created – User initialized

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:

• 200 OK – Module created

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:

• 204 No Content – Deleted Module

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:

• 200 OK – Updated Module

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)

• description (string) – (required)

• featuredImage (string)

• filePath (string)

• hardware (string) – (required)

• modules[] (string)

• name (string) – (required)

• public (boolean) – (required)

• tags[] (string)

• type (string) – (required)

Status Codes:

• 200 OK – Server created

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:

• 200 OK – Server created

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:

• 204 No Content – Server deleted

GET /servers/{id}

Get Server with a given ID

Parameters:

• id (string)

Status Codes:

• 200 OK – A Server

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:

• 204 No Content – Server started

PUT /servers/{id}/stop

Stop a Server with given ID

Parameters:

• id (string)

Status Codes:

• 204 No Content – Server stopped

DELETE /template

Delete a Template with a given ID

Query Parameters:

• templateId (string)

Status Codes:

• 204 No Content – Template deleted

PATCH /template

Update Template with given id.

Query Parameters:

• templateId (string)

Request JSON Object:

• applicationType (string)

• creator (string)

• description (string)

• featuredImage (string)

• filePath (string)

• hardware (string)

• modules[] (string)

• name (string)

• public (boolean)

• tags[] (string)

Status Codes:

• 200 OK – Template updated

POST /template

Create a new Template.

Request JSON Object:

• applicationType (string) – (required)

• creator (string) – (required)

• description (string) – (required)

• featuredImage (string)

• filePath (string)

• hardware (string) – (required)

• modules[] (string)

• name (string) – (required)

• public (boolean) – (required)

• tags[] (string)

• type (string) – (required)

Status Codes:

• 200 OK – Template created

Response JSON Object:

• _id (string)

• applicationType (string) – (required)

• creator (string) – (required)

• description (string) – (required)

• featuredImage (string)

• filePath (string)

• hardware (string) – (required)

• modules[] (string)

• name (string) – (required)

• public (boolean) – (required)

• 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)

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

• [].featuredImage (string)

• [].filePath (string)

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

• [].modules[] (string)

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

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

• [].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)

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

• [].featuredImage (string)

• [].filePath (string)

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

• [].modules[] (string)

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

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

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

• [].tags[] (string)

• [].timestamp (string)

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

GET /version

Get API version.

Status Codes:

• 200 OK – API version

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:

• 200 OK – File created

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 /whoami

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

Status Codes:

• 200 OK – the logged in username