hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 15:33:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated JupyterHub's REST API doc

Browse Source
This commit is contained in:
Uzochukwu Precious
2022-10-22 10:02:39 +01:00
parent e7284b65ad
commit eb8f338186
1 changed files with 49 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/source/reference/rest.md
View File

@@ -4,22 +4,25 @@
This section will give you information on: This section will give you information on:
- what you can do with the API - [What you can do with the API](#what-you-can-do-with-the-api)
- create an API token - [How to create an API token](#create-an-api-token)
- add API tokens to the config files - [Assigning permissions to a token](#assigning-permissions-to-a-token)
- make an API request programmatically using the requests library - [Updating to admin services](#updating-to-admin-services)
- learn more about JupyterHub's API - [Making an API request programmatically using the requests library](#make-an-api-request)
- [Paginating API requests](#paginating-api-requests)
- [Enabling users to spawn multiple named-servers via the API](#enabling-users-to-spawn-multiple-named-servers-via-the-api)
- [Learn more about JupyterHub's API](#learn-more-about-the-api)
## What you can do with the API ## What you can do with the API
Using the [JupyterHub REST API][], you can perform actions on the Hub, Using the [JupyterHub REST API][], you can perform actions on the Hub,
such as: such as:
- checking which users are active - Checking which users are active
- adding or removing users - Adding or removing users
- stopping or starting single user notebook servers - Stopping or starting single user notebook servers
- authenticating services - Authenticating services
- communicating with an individual Jupyter server's REST API - Communicating with an individual Jupyter server's REST API
A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)
API provides a standard way for users to get and send information to the API provides a standard way for users to get and send information to the
@@ -27,21 +30,25 @@ Hub.
## Create an API token ## Create an API token
To send requests using JupyterHub API, you must pass an API token with To send requests using the JupyterHub API, you must pass an API token with
the request. the request.
The preferred way of generating an API token is: The preferred way of generating an API token is by running:
```bash ```bash
openssl rand -hex 32 openssl rand -hex 32
``` ```
This `openssl` command generates a potential token that can then be The `openssl` command generates a potential token that can then be
added to JupyterHub using `.api_tokens` configuration setting in added to JupyterHub using `.api_tokens` configuration setting in
`jupyterhub_config.py`. `jupyterhub_config.py`.
Alternatively, use the `jupyterhub token` command to generate a token ```{note}
for a specific hub user by passing the 'username': The api_tokens configuration has been softly deprecated since the introduction of services.
```
Alternatively, you can use the `jupyterhub token` command to generate a token
for a specific hub user by passing the **_username_**:
```bash ```bash
jupyterhub token <username> jupyterhub token <username>
@@ -53,9 +60,19 @@ it for the given user with the Hub's database.
In [version 0.8.0](../changelog.md), a token request page for In [version 0.8.0](../changelog.md), a token request page for
generating an API token is available from the JupyterHub user interface: generating an API token is available from the JupyterHub user interface:
![Request API token page](../images/token-request.png) ```{figure} ../images/token-request.png
---
name: token-request
---
JupyterHub's API token page
```
![API token success page](../images/token-request-success.png) ```{figure} ../images/token-request-success.png
---
name: token-request-success
---
JupyterHub's API token success page
```
## Assigning permissions to a token ## Assigning permissions to a token
@@ -67,25 +84,26 @@ Prior to JupyterHub 2.0, there were two levels of permissions:
where a token would always have full permissions to do whatever its owner could do. where a token would always have full permissions to do whatever its owner could do.
In JupyterHub 2.0, In JupyterHub 2.0,
specific permissions are now defined as 'scopes', specific permissions are now defined as '**scopes**',
and can be assigned both at the user/service level, and can be assigned both at the user/service level,
and at the individual token level. and at the individual token level.
This allows e.g. a user with full admin permissions to request a token with limited permissions. This allows e.g. a user with full admin permissions to request a token with limited permissions.
### Updating to admin services ## Updating to admin services
```{note}
The `api_tokens` configuration has been softly deprecated since the introduction of services. The `api_tokens` configuration has been softly deprecated since the introduction of services.
We have no plans to remove it, We have no plans to remove it,
but deployments are encouraged to use service configuration instead. but deployments are encouraged to use service configuration instead.
```
If you have been using `api_tokens` to create an admin user If you have been using `api_tokens` to create an admin user
and a token for that user to perform some automations, and the token for that user to perform some automations, then
the services mechanism may be a better fit. the services' mechanism may be a better fit if you have the following configuration:
If you have the following configuration:
```python ```python
c.JupyterHub.admin_users = {"service-admin",} c.JupyterHub.admin_users = {"service-admin"}
c.JupyterHub.api_tokens = { c.JupyterHub.api_tokens = {
"secret-token": "service-admin", "secret-token": "service-admin",
} }
@@ -103,9 +121,8 @@ c.JupyterHub.services = [
}, },
] ]
# roles are new in JupyterHub 2.0 # roles were introduced in JupyterHub 2.0
# prior to 2.0, only 'admin': True or False # prior to 2.0, only "admin": True or False was available
# was available
c.JupyterHub.load_roles = [ c.JupyterHub.load_roles = [
{ {
@@ -176,7 +193,7 @@ r.json()
``` ```
The same API token can also authorize access to the [Jupyter Notebook REST API][] The same API token can also authorize access to the [Jupyter Notebook REST API][]
provided by notebook servers managed by JupyterHub if it has the necessary `access:users:servers` scope: provided by notebook servers managed by JupyterHub if it has the necessary `access:users:servers` scope.
(api-pagination)= (api-pagination)=
@@ -245,7 +262,7 @@ with your request, in which case a response will look like:
where the list results (same as pre-2.0) will be in `items`, where the list results (same as pre-2.0) will be in `items`,
and pagination info will be in `_pagination`. and pagination info will be in `_pagination`.
The `next` field will include the offset, limit, and URL for requesting the next page. The `next` field will include the `offset`, `limit`, and `url` for requesting the next page.
`next` will be `null` if there is no next page. `next` will be `null` if there is no next page.
Pagination is governed by two configuration options: Pagination is governed by two configuration options:
@@ -259,7 +276,7 @@ Pagination is enabled on the `GET /users`, `GET /groups`, and `GET /proxy` REST
## Enabling users to spawn multiple named-servers via the API ## Enabling users to spawn multiple named-servers via the API
With JupyterHub version 0.8, support for multiple servers per user has landed. Support for multiple servers per user was introduced in JupyterHub [version 0.8.](../changelog.md)
Prior to that, each user could only launch a single default server via the API Prior to that, each user could only launch a single default server via the API
like this: like this:
@@ -275,7 +292,7 @@ First you must enable named-servers by including the following setting in the `j
`c.JupyterHub.allow_named_servers = True` `c.JupyterHub.allow_named_servers = True`
If using the [zero-to-jupyterhub-k8s](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) set-up to run JupyterHub, If you are using the [zero-to-jupyterhub-k8s](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) set-up to run JupyterHub,
then instead of editing the `jupyterhub_config.py` file directly, you could pass then instead of editing the `jupyterhub_config.py` file directly, you could pass
the following as part of the `config.yaml` file, as per the [tutorial](https://zero-to-jupyterhub.readthedocs.io/en/latest/): the following as part of the `config.yaml` file, as per the [tutorial](https://zero-to-jupyterhub.readthedocs.io/en/latest/):
@@ -303,8 +320,9 @@ or kubernetes pods.
## Learn more about the API ## Learn more about the API
You can see the full [JupyterHub REST API][] for details. You can see the full [JupyterHub REST API][] for more details.
[openapi initiative]: https://www.openapis.org/ [openapi initiative]: https://www.openapis.org/
[jupyterhub rest api]: ./rest-api [jupyterhub rest api]: ./rest-api
[scopes]: https://jupyterhub.readthedocs.io/en/stable/rbac/scopes.html
[jupyter notebook rest api]: https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/HEAD/notebook/services/api/api.yaml [jupyter notebook rest api]: https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/HEAD/notebook/services/api/api.yaml