add REST API to docs

include local build, even though it's not as nice as petstore.
Due the that, link to petstore as well.

docs/Makefile

@@ -51,7 +51,15 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
-html:
+node_modules: package.json
+	npm install && touch node_modules
+
+rest-api: source/_static/rest-api/index.html
+
+source/_static/rest-api/index.html: rest-api.yml node_modules
+	npm run rest-api
+
+html: rest-api
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "jupyterhub-docs-build",
+  "version": "0.0.0",
+  "description": "build JupyterHub swagger docs",
+  "scripts": {
+    "rest-api": "bootprint openapi ./rest-api.yml source/_static/rest-api"
+  },
+  "author": "",
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "bootprint": "^0.8.5",
+    "bootprint-openapi": "^0.17.0"
+  }
+}

docs/rest-api.yml

@@ -3,7 +3,8 @@ swagger: '2.0'
 info:
   title: JupyterHub
   description: The REST API for JupyterHub
-  version: 0.4.0
+  version: 0.7.0
+  license: BSD-3-Clause
 schemes:
   - http
 securityDefinitions:

docs/source/api/index.rst

@@ -13,3 +13,4 @@
     spawner
     user
     services.auth
+    rest

docs/source/api/rest.md

@@ -0,0 +1,38 @@
+# The JupyterHub REST API
+
+JupyterHub has a [REST API](https://en.wikipedia.org/wiki/Representational_state_transfer), which you can use to perform actions on the Hub,
+such as checking what users are active, adding or removing users,
+stopping or starting user servers, etc.
+
+To get access to the JupyterHub API, you must create a token.
+You can create a token for a particular user with:
+
+    jupyterhub token USERNAME
+
+Alternately, you can load API tokens in your `jupyterhub_config.py`:
+
+```python
+c.JupyterHub.api_tokens = {
+    'secret-token': 'username',
+}
+```
+
+To authenticate your requests, pass this token in the Authorization header.
+For example, to list users with requests in Python:
+
+```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()
+```
+
+You can see the full  [REST API Spec](../_static/rest-api/index.html) for details.
+A fancier version of the same information can be viewed [on swagger's petstore][].
+
+[on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default