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/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