hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-17 15:03: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:
- what you can do with the API
- create an API token
- add API tokens to the config files
- make an API request programmatically using the requests library
- learn more about JupyterHub's API
- [What you can do with the API](#what-you-can-do-with-the-api)
- [How to create an API token](#create-an-api-token)
- [Assigning permissions to a token](#assigning-permissions-to-a-token)
- [Updating to admin services](#updating-to-admin-services)
- [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
Using the [JupyterHub REST API][], you can perform actions on the Hub,
such as:
- checking which users are active
- adding or removing users
- stopping or starting single user notebook servers
- authenticating services
- communicating with an individual Jupyter server's REST API
- Checking which users are active
- Adding or removing users
- Stopping or starting single user notebook servers
- Authenticating services
- Communicating with an individual Jupyter server's REST API
A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)
API provides a standard way for users to get and send information to the
@@ -27,21 +30,25 @@ Hub.
## 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 preferred way of generating an API token is:
The preferred way of generating an API token is by running:
```bash
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
`jupyterhub_config.py`.
Alternatively, use the `jupyterhub token` command to generate a token
for a specific hub user by passing the 'username':
```{note}
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
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
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
@@ -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.
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 at the individual token level.
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.
We have no plans to remove it,
but deployments are encouraged to use service configuration instead.
```
If you have been using `api_tokens` to create an admin user
and a token for that user to perform some automations,
the services mechanism may be a better fit.
If you have the following configuration:
and the token for that user to perform some automations, then
the services' mechanism may be a better fit if you have the following configuration:
```python
c.JupyterHub.admin_users = {"service-admin",}
c.JupyterHub.admin_users = {"service-admin"}
c.JupyterHub.api_tokens = {
"secret-token": "service-admin",
}
@@ -103,9 +121,8 @@ c.JupyterHub.services = [
},
]
# roles are new in JupyterHub 2.0
# prior to 2.0, only 'admin': True or False
# was available
# roles were introduced in JupyterHub 2.0
# prior to 2.0, only "admin": True or False was available
c.JupyterHub.load_roles = [
{
@@ -176,7 +193,7 @@ r.json()
```
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)=
@@ -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`,
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.
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
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
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`
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
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
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/
[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