From 19ae38c108b24e6932d566fbdbf7feab3a80d324 Mon Sep 17 00:00:00 2001
From: Min RK <benjaminrk@gmail.com>
Date: Sat, 23 Jul 2016 12:05:25 +0200
Subject: [PATCH] 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             | 10 +++++++++-
 docs/package.json         | 14 ++++++++++++++
 docs/rest-api.yml         |  3 ++-
 docs/source/api/index.rst |  1 +
 docs/source/api/rest.md   | 38 ++++++++++++++++++++++++++++++++++++++
 5 files changed, 64 insertions(+), 2 deletions(-)
 create mode 100644 docs/package.json
 create mode 100644 docs/source/api/rest.md

diff --git a/docs/Makefile b/docs/Makefile
index aae144bf..9ca1fcaa 100644
--- a/docs/Makefile
+++ b/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."
diff --git a/docs/package.json b/docs/package.json
new file mode 100644
index 00000000..a218ddff
--- /dev/null
+++ b/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"
+  }
+}
diff --git a/docs/rest-api.yml b/docs/rest-api.yml
index de2b8847..d377865a 100644
--- a/docs/rest-api.yml
+++ b/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:
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index e543ee82..345f8542 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -13,3 +13,4 @@
     spawner
     user
     services.auth
+    rest
diff --git a/docs/source/api/rest.md b/docs/source/api/rest.md
new file mode 100644
index 00000000..c4b18714
--- /dev/null
+++ b/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