From 10c54353da723ef005d9f1143ca713d582d670ff Mon Sep 17 00:00:00 2001 From: lumenCodes Date: Tue, 18 Oct 2022 02:19:33 +0100 Subject: [PATCH 1/4] Rest Api doc update --- docs/source/reference/rest.md | 46 +++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/source/reference/rest.md b/docs/source/reference/rest.md index 12f8f44e..cbf45016 100644 --- a/docs/source/reference/rest.md +++ b/docs/source/reference/rest.md @@ -4,15 +4,20 @@ 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) +- [how to add API tokens to the config files](#) +- [how to make an API request programmatically using the requests library](#make-an-api-request) +- [where to learn more about JupyterHub's API](#learn-more-about-the-api) + + +Before we discuss about JupyterHub's REST API, you can learn about [REST APIs here](https://en.wikipedia.org/wiki/Representational_state_transfer). A REST +API provides a standard way for users to get and send information to the +Hub. ## What you can do with the API -Using the [JupyterHub REST API][], you can perform actions on the Hub, +Using the [JupyterHub REST API](https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html#/default/delete_groups__name_), you can perform actions on the Hub, such as: - checking which users are active @@ -21,16 +26,14 @@ such as: - 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 -Hub. + ## Create an API token To send requests using 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 openssl rand -hex 32 @@ -41,7 +44,7 @@ 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': +for a specific hub user by passing the " **username**": ```bash jupyterhub token @@ -123,9 +126,9 @@ c.JupyterHub.load_roles = [ ``` The token will have the permissions listed in the role -(see [scopes][] for a list of available permissions), +(see [scopes](https://jupyterhub.readthedocs.io/en/stable/rbac/scopes.html#scopes-in-jupyterhub) for a list of available permissions), but there will no longer be a user account created to house it. -The main noticeable difference is that there will be no notebook server associated with the account +The main noticeable difference between a configuration and a service is that there will be no notebook server associated with the account and the service will not show up in the various user list pages and APIs. ## Make an API request @@ -136,8 +139,8 @@ Authorization header. ### Use requests Using the popular Python [requests](https://docs.python-requests.org) -library, here's example code to make an API request for the users of a JupyterHub -deployment. An API GET request is made, and the request sends an API token for +library, (here's example code to make an API request for the users of a JupyterHub +deployment) an API GET request is made, and the request sends an API token for authorization. The response contains information about the users: ```python @@ -175,10 +178,11 @@ r.raise_for_status() 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: +The same API token can also authorize access to the [Jupyter Notebook REST API](https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html#/) +provided by notebook servers managed by JupyterHub if it has the necessary `access:users:servers` scope. +

 

+ -(api-pagination)= ## Paginating API requests @@ -275,7 +279,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,7 +307,7 @@ 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](https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html#/) for details. [openapi initiative]: https://www.openapis.org/ [jupyterhub rest api]: ./rest-api From 28de35facd347d902e5de3bc4416e96ea4d89cbe Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 18 Oct 2022 01:25:27 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/reference/rest.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/source/reference/rest.md b/docs/source/reference/rest.md index cbf45016..42bfc6eb 100644 --- a/docs/source/reference/rest.md +++ b/docs/source/reference/rest.md @@ -10,7 +10,6 @@ This section will give you information on: - [how to make an API request programmatically using the requests library](#make-an-api-request) - [where to learn more about JupyterHub's API](#learn-more-about-the-api) - Before we discuss about JupyterHub's REST API, you can learn about [REST APIs here](https://en.wikipedia.org/wiki/Representational_state_transfer). A REST API provides a standard way for users to get and send information to the Hub. @@ -26,12 +25,10 @@ such as: - authenticating services - communicating with an individual Jupyter server's REST API - - ## Create an API token To send requests using JupyterHub API, you must pass an API token with -the request. +the request. The preferred way of generating an API token is by running: @@ -179,11 +176,10 @@ r.json() ``` The same API token can also authorize access to the [Jupyter Notebook REST API](https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html#/) -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. +

 

- - ## Paginating API requests ```{versionadded} 2.0 From cf2ec324b78bc2b4e8f8148b8cdf020dcaf195ca Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 26 Oct 2022 17:23:18 +0000 Subject: [PATCH 3/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/reference/rest.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/reference/rest.md b/docs/source/reference/rest.md index 1df93524..526727c0 100644 --- a/docs/source/reference/rest.md +++ b/docs/source/reference/rest.md @@ -4,7 +4,6 @@ This section will give you information on: - - What you can do with the API - How to create an API token - Assigning permissions to a token @@ -16,7 +15,7 @@ This section will give you information on: Before we discuss about JupyterHub's REST API, you can learn about [REST APIs here](https://en.wikipedia.org/wiki/Representational_state_transfer). A REST API provides a standard way for users to get and send information to the -Hub. +Hub. ## What you can do with the API @@ -197,7 +196,6 @@ 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. - ## Paginating API requests ```{versionadded} 2.0 @@ -323,7 +321,6 @@ or kubernetes pods. You can see the full [JupyterHub REST API][] for more details. - [openapi initiative]: https://www.openapis.org/ [jupyterhub rest api]: ./rest-api [scopes]: ../rbac/scopes.md From 438b285670f0cd8b2d592c7a73a9f2a6fb932b83 Mon Sep 17 00:00:00 2001 From: lumenCodes Date: Wed, 26 Oct 2022 18:44:51 +0100 Subject: [PATCH 4/4] I effected PR requested changes --- docs/source/reference/rest.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/source/reference/rest.md b/docs/source/reference/rest.md index 526727c0..36db7271 100644 --- a/docs/source/reference/rest.md +++ b/docs/source/reference/rest.md @@ -19,7 +19,7 @@ Hub. ## What you can do with the API -Using the [JupyterHub REST API](https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html#/default/delete_groups__name_), you can perform actions on the Hub, +Using the [JupyterHub REST API][], you can perform actions on the Hub, such as: - Checking which users are active @@ -140,9 +140,9 @@ c.JupyterHub.load_roles = [ ``` The token will have the permissions listed in the role -(see [scopes](https://jupyterhub.readthedocs.io/en/stable/rbac/scopes.html#scopes-in-jupyterhub) for a list of available permissions), +(see [scopes][] for a list of available permissions), but there will no longer be a user account created to house it. -The main noticeable difference between a configuration and a service is that there will be no notebook server associated with the account +The main noticeable difference between a user and a service is that there will be no notebook server associated with the account and the service will not show up in the various user list pages and APIs. ## Make an API request @@ -153,9 +153,8 @@ Authorization header. ### Use requests Using the popular Python [requests](https://docs.python-requests.org) -library, (here's example code to make an API request for the users of a JupyterHub -deployment) an API GET request is made, and the request sends an API token for -authorization. The response contains information about the users: +library, an API GET request is made, and the request sends an API token for +authorization. The response contains information about the users, here's example code to make an API request for the users of a JupyterHub deployment ```python import requests @@ -196,6 +195,8 @@ 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. +(api-pagination)= + ## Paginating API requests ```{versionadded} 2.0