mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-09 11:03:00 +00:00
62 lines
1.6 KiB
Markdown
62 lines
1.6 KiB
Markdown
# Using JupyterHub's REST API
|
|
|
|
Using the JupyterHub [REST API](https://en.wikipedia.org/wiki/Representational_state_transfer),
|
|
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
|
|
|
|
## Creating an API token
|
|
To send requests using JupyterHub API, you must pass an API token with the
|
|
request. You can create a token for an individual user using the following
|
|
command:
|
|
|
|
jupyterhub token USERNAME
|
|
|
|
|
|
## Adding tokens to the config file
|
|
You may also add a dictionary of API tokens and usernames to the hub's
|
|
configuration file, `jupyterhub_config.py`:
|
|
|
|
```python
|
|
c.JupyterHub.api_tokens = {
|
|
'secret-token': 'username',
|
|
}
|
|
```
|
|
|
|
|
|
## Making an API request
|
|
|
|
To authenticate your requests, pass the API token in the request's
|
|
Authorization header.
|
|
|
|
**Example: List the hub's users**
|
|
|
|
Using the popular Python requests library, the following code sends an API
|
|
request and an API token for authorization:
|
|
|
|
```python
|
|
import requests
|
|
|
|
api_url = 'http://127.0.0.1:8081/hub/api'
|
|
|
|
r = requests.get(api_url + '/users',
|
|
headers={
|
|
'Authorization': 'token %s' % token,
|
|
}
|
|
)
|
|
|
|
r.raise_for_status()
|
|
users = r.json()
|
|
```
|
|
|
|
|
|
## Learning more about the API
|
|
|
|
You can see the full [REST API Spec](../_static/rest-api/index.html) for details.
|
|
The same REST API Spec can be viewed in a more visually appealing style [on swagger's petstore][].
|
|
Both resources contain the same information and differ only in its display.
|
|
|
|
[on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
|