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.”

---

POST /auth/authorize

Create an authorization URL for the user

Status Codes:

• 200 OK – Authorization URL created successfully

Response JSON Object:

• authorizationUrl (string)

POST /auth/logout

Logout the user

Request JSON Object:

• id_token (string) – (required)

Status Codes:

• 200 OK – Logout successful

Response JSON Object:

• logoutUrl (string)

POST /auth/refresh

Refresh an expired access token

Request JSON Object:

• refresh_token (string) – (required)

Status Codes:

• 200 OK – Token refresh successful

• 400 Bad Request – Token refresh failed

Response JSON Object:

• access_token (string) – (required)

• expires_at (number) – (required)

• expires_in (number) – (required)

• id_token (string) – (required)

• refresh_token (string)

• scope (string) – (required)

• token_type (string) – (required)

POST /auth/token

Exchange the authorization code for an access token.

Request JSON Object:

• code (string) – (required)

Status Codes:

• 200 OK – Token exchange successful

• 400 Bad Request – Token exchange failed

Response JSON Object:

• access_token (string) – (required)

• expires_at (number) – (required)

• expires_in (number) – (required)

• id_token (string) – (required)

• refresh_token (string)

• scope (string) – (required)

• token_type (string) – (required)

GET /authenticated

Verify the access to a protected route.

Status Codes:

• 200 OK – Route is protected

GET /datasets

Get Datasets for a given user.

Status Codes:

• 200 OK – An array of Datasets

Response JSON Object:

• []._id (string)

• [].description (string)

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

• [].owner (string)

• [].write_access (boolean)

POST /datasets

Create a new Dataset

This creates an empty directory on the file system.

Request JSON Object:

• description (string)

• name (string) – (required)

• owner (string)

• write_access (boolean)

Status Codes:

• 200 OK – Dataset created

Response JSON Object:

• _id (string)

• description (string)

• name (string) – (required)

• owner (string)

• write_access (boolean)

DELETE /datasets/{id}

Delete Dataset with given ID

Parameters:

• id (string)

Status Codes:

• 204 No Content – Deleted Dataset

PATCH /datasets/{id}

Update Dataset with given ID

Parameters:

• id (string)

Request JSON Object:

• description (string)

• name (string)

Status Codes:

• 200 OK – Updated Dataset

GET /datasets/{id}/access

Get accessible users for a Dataset with a given ID and type

Parameters:

• id (string)

Query Parameters:

• type (string)

Status Codes:

• 200 OK – An array of users with their access levels

Response JSON Object:

• [].access (string)

• [].entity (string)

POST /datasets/{id}/revoke

Revoke access to a Dataset with a given ID

Parameters:

• id (string)

Request JSON Object:

• groupArray (string)

• orgArray (string)

• relation (string) – (required)

• userArray[] (string)

Status Codes:

• 204 No Content – revoke Dataset access success.

POST /datasets/{id}/share

Share a Dataset with a given ID

Parameters:

• id (string)

Request JSON Object:

• groupArray[] (string)

• orgArray[] (string)

• relation (string) – (required)

• userArray[] (string)

Status Codes:

• 204 No Content – Dataset share success.

GET /groups

Get all Groups.

Status Codes:

• 200 OK – Array of Groups.

Response JSON Object:

• []._id (string)

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

POST /groups

Create a new Group.

Request JSON Object:

• name (string) – (required)

Status Codes:

• 200 OK – Group POST success.

Response JSON Object:

• _id (string)

• name (string) – (required)

DELETE /groups/{id}

Delete a Group by ID.

Parameters:

• id (string)

Status Codes:

• 204 No Content – Group DELETE success.

GET /groups/{id}

Get a Group by ID.

Parameters:

• id (string)

Status Codes:

• 200 OK – Group details.

Response JSON Object:

• _id (string)

• name (string) – (required)

PATCH /groups/{id}

Update the groupName of a Group by ID.

Parameters:

• id (string)

Request JSON Object:

• name (string) – (required)

Status Codes:

• 200 OK – Group PATCH success.

Response JSON Object:

• _id (string)

• name (string) – (required)

GET /groups/{id}/members

Get all members of a Group.

Parameters:

• id (string)

Status Codes:

• 200 OK – Array of Group members.

Response JSON Object:

• [] (string)

POST /groups/{id}/members

Add a member to a Group.

Parameters:

• id (string)

Query Parameters:

• memberEmail (string)

Status Codes:

• 200 OK – Group member added successfully.

DELETE /groups/{id}/members/{memberEmail}

Remove a member from a Group.

Parameters:

• id (string)

• memberEmail (string)

Status Codes:

• 204 No Content – Group member removed successfully.

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.

Status Codes:

• 200 OK – An array of Modules

Response JSON Object:

• []._id (string)

• [].description (string)

• [].featured (boolean)

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

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

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

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

• luaModuleFile[].arguments[] (string)

• luaModuleFile[].id (string)

• name (string) – (required)

• version (string) – (required)

• write_access (boolean)

Status Codes:

• 200 OK – Module created

Response JSON Object:

• _id (string)

• description (string)

• featured (boolean)

• luaModuleFile[].arguments[] (string)

• luaModuleFile[].id (string)

• name (string) – (required)

• owner (string)

• version (string) – (required)

• write_access (boolean)

DELETE /modules/{id}

Delete a Module with given ID

Parameters:

• id (string)

Status Codes:

• 204 No Content – Deleted Module

PATCH /modules/{id}

Update Module with given ID

Parameters:

• id (string)

Request JSON Object:

• description (string)

• luaModuleFile[].arguments[] (string)

• luaModuleFile[].id (string)

• name (string)

• version (string)

Status Codes:

• 200 OK – Updated Module

GET /modules/{id}/access

Get accessible users for a Module with a given ID and type

Parameters:

• id (string)

Query Parameters:

• type (string)

Status Codes:

• 200 OK – An array of users with their access levels

Response JSON Object:

• [].access (string)

• [].entity (string)

POST /modules/{id}/revoke

Revoke access to a Module with a given ID

Parameters:

• id (string)

Request JSON Object:

• groupArray[] (string)

• orgArray[] (string)

• relation (string) – (required)

• userArray[] (string)

Status Codes:

• 204 No Content – Module revoke access success.

POST /modules/{id}/share

Share a Module with a given ID

Parameters:

• id (string)

Request JSON Object:

• groupArray[] (string)

• orgArray[] (string)

• relation (string) – (required)

• userArray[] (string)

Status Codes:

• 204 No Content – Module share success.

POST /secret/share/{id}

Share a Secret with a given ID

Parameters:

• id (string)

Request JSON Object:

• groupArray[] (string)

• orgArray[] (string)

• relation (string) – (required)

• userArray[] (string)

Status Codes:

• 204 No Content – Secret share success.

DELETE /secret/{id}

Delete a Secret with a given ID

Parameters:

• id (string)

Status Codes:

• 204 No Content – Secret DEL success.

GET /secret/{id}

Get Secret with a given ID

Parameters:

• id (string)

Status Codes:

• 200 OK – A Secret

PATCH /secret/{id}

Update a Secret with a given ID

Parameters:

• id (string)

Request JSON Object:

• description (string)

• mount_path (string)

• secretName (string)

Status Codes:

• 204 No Content – Success updating Secret

POST /secret/{id}/revoke

Remove access to a Secret with a given ID

Parameters:

• id (string)

Request JSON Object:

• groupArray[] (string)

• orgArray[] (string)

• relation (string) – (required)

• userArray[] (string)

Status Codes:

• 204 No Content – Secret share success.

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)

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

• description (string)

• mount_path (string)

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

Request JSON Object:

• applicationType (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:

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

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

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

• datasets[] (string)

• description (string)

• featuredImage (string)

• filePath (string)

• hardware (string)

• modules[] (string)

• name (string)

• public (boolean)

• secrets[] (string)

• tags[] (string)

Status Codes:

• 200 OK – Template updated

POST /template

Create a new Template.

Request JSON Object:

• applicationType (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:

• 200 OK – Template created

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:

• 200 OK – API version

POST /volume/file

Create a new file in a specified directory.

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