From 8662a4a80771fdb251ab35e80b83af71fc326891 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 25 Jul 2017 15:23:25 -0700 Subject: [PATCH] Edit networking and REST API usage docs --- docs/source/networking-basics.md | 36 ++++++++++++++++------------- docs/source/rest.md | 39 ++++++++++++++++++++------------ 2 files changed, 45 insertions(+), 30 deletions(-) diff --git a/docs/source/networking-basics.md b/docs/source/networking-basics.md index 728b892e..fad239ce 100644 --- a/docs/source/networking-basics.md +++ b/docs/source/networking-basics.md @@ -1,39 +1,41 @@ # Networking basics -## Configuring the Proxy's IP address and port +## Set the Proxy's IP address and port + The Proxy's main IP address setting determines where JupyterHub is available to users. By default, JupyterHub is configured to be available on all network interfaces -(`''`) on port 8000. **Note**: Use of `'*'` is discouraged for IP configuration; +(`''`) on port 8000. *Note*: Use of `'*'` is discouraged for IP configuration; instead, use of `'0.0.0.0'` is preferred. -Changing the IP address and port can be done with the following command line -arguments: +Changing the Proxy's main IP address and port can be done with the following +JupyterHub **command line options**: ```bash jupyterhub --ip=192.168.1.2 --port=443 ``` -Or by placing the following lines in a configuration file: +Or by placing the following lines in a **configuration file**, +`jupyterhub_config.py`: ```python c.JupyterHub.ip = '192.168.1.2' c.JupyterHub.port = 443 ``` -Port 443 is used as an example since 443 is the default port for SSL/HTTPS. +Port 443 is used in the examples since 443 is the default port for SSL/HTTPS. -Configuring only the main IP and port of JupyterHub should be sufficient for most deployments of JupyterHub. -However, more customized scenarios may need additional networking details to -be configured. +Configuring only the main IP and port of JupyterHub should be sufficient for +most deployments of JupyterHub. However, more customized scenarios may need +additional networking details to be configured. +## Set the Proxy's REST API communication IP address and port (optional) -## Configuring the Proxy's REST API communication IP address and port (optional) The Hub service talks to the proxy via a REST API on a secondary port, whose network interface and port can be configured separately. -By default, this REST API listens on port 8081 of localhost only. +By default, this REST API listens on port 8081 of `localhost` only. -If running the Proxy separate from the Hub, -configure the REST API communication IP address and port with: +If running the Proxy separate from the Hub, configure the REST API communication +IP address and port by adding this to the `jupyterhub_config.py` file: ```python # ideally a private network address @@ -42,9 +44,11 @@ c.JupyterHub.proxy_api_port = 5432 ``` ## Configuring the Hub if Spawners or Proxy are remote or isolated in containers -The Hub service also listens only on localhost (port 8080) by default. -The Hub needs needs to be accessible from both the proxy and all Spawners. -When spawning local servers, an IP address setting of localhost is fine. + +The Hub service listens only on `localhost` (port 8080) by default. +The Hub needs to be accessible from both the proxy and all Spawners. +When spawning local servers, an IP address setting of `localhost` is fine. + If *either* the Proxy *or* (more likely) the Spawners will be remote or isolated in containers, the Hub must listen on an IP that is accessible. diff --git a/docs/source/rest.md b/docs/source/rest.md index 68afdd5e..827a74c6 100644 --- a/docs/source/rest.md +++ b/docs/source/rest.md @@ -1,5 +1,15 @@ # Using JupyterHub's REST API +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 + Using the [JupyterHub REST API][], you can perform actions on the Hub, such as: @@ -12,16 +22,16 @@ 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 -## 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 +## Add API tokens to the config file -## 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`: @@ -31,16 +41,16 @@ c.JupyterHub.api_tokens = { } ``` - -## Making an API request +## Make an API request To authenticate your requests, pass the API token in the request's Authorization header. -**Example: List the hub's users** +### Use requests -Using the popular Python requests library, the following code sends an API -request and an API token for authorization: +Using the popular Python [requests](http://docs.python-requests.org/en/master/) +library, here's example code to get users of a JupyterHub deployment. An API +is made, and the request sends an API token for authorization: ```python import requests @@ -57,18 +67,19 @@ r.raise_for_status() users = r.json() ``` -Note that the token authorizes JupyterHub REST API requests. The same token -does **not** authorize access to the [Jupyter Notebook REST API][] provided -by notebook servers managed by JupyterHub. +Note that the API token authorizes **JupyterHub** REST API requests. The same +token does **not** authorize access to the [Jupyter Notebook REST API][] +provided by notebook servers managed by JupyterHub. A different token is used +to access the **Jupyter Notebook** API. -## Learning more about the API +## Learn more about the API -You can see the full [JupyterHub REST API][] for details. -The same REST API Spec can be viewed in a more interactive style [on swagger's petstore][]. +You can see the full [JupyterHub REST API][] for details. This REST API Spec can +be viewed in a more [interactive style on swagger's petstore][]. Both resources contain the same information and differ only in its display. Note: The Swagger specification is being renamed the [OpenAPI Initiative][]. -[on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default +[interactive style on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default [OpenAPI Initiative]: https://www.openapis.org/ [JupyterHub REST API]: ./_static/rest-api/index.html [Jupyter Notebook REST API]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml