Merge ~bloodearnest/snapstore-client:api-docs into snapstore-client:master

[Simon Davy]

initial api docs for overrides

initial api docs for overrides

f33c99a... by Simon Davy on 2017-10-31

add missing links

[Daniel Manrique (roadmr)]

There's some pseudoformat in this document which suggests the intent is markdown rather than rst, in which case I'd suggest checking it with e.g. python-markdown, because right now it doesn't render very nicely. Even if it's not intended for rendering, it'd make sense to still adhere to markdown so it *can* be rendered :)

I was initially super confused and was about to suggest this document was too unfriendly, but then went back and realized the audience are developers who'll interact with the API, so it should be OK to be a bit rough on them.

Also caught some typos and other minor things below.

review: Needs Fixing

e2369aa... by Simon Davy on 2017-11-01

Move documentation to subdir and make proper markdown

Builds using the documentation-builder tool

bc2dffe... by Simon Davy on 2017-11-01

add make docs command

[Simon Davy (bloodearnest)]

Thanks, have addressed formatting and typo issues. The goal of this MP is a first draft to tick the box and have something to iterate on. As such, full docs for macaroons is out of scope for this MP

6f26b12... by Simon Davy on 2017-11-01

add index page and titles

[Colin Watson (cjwatson)]

review: Approve

b54a5a4... by Simon Davy on 2017-11-01

fix typos and minor rewording/reordering

[Daniel Manrique (roadmr)]

+1 from me, thanks!

review: Approve

edf1bf9... by Simon Davy on 2017-11-01

s/snapstore/snap store/

diff --git a/.gitignore b/.gitignore
index 2c97cd0..5d2c033 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ __pycache__/
 
 /.coverage
 /htmlcov
+docs/build
diff --git a/Makefile b/Makefile
index d13c088..a3b3b78 100644
--- a/Makefile
+++ b/Makefile
@@ -33,6 +33,13 @@ test: $(ENV)/dev
 	$(PYTHON3) -m unittest $(TESTS) 2>&1
 	$(MAKE) --silent lint
 
+/snap/bin/documentation-builder:
+	sudo snap install documentation-builder
+
+docs: /snap/bin/documentation-builder
+	documentation-builder --base-dir docs --output-path docs/build
+
+
 lint:
 	$(FLAKE8) $(SERVICE_PACKAGE)
 
@@ -43,10 +50,10 @@ coverage: $(ENV)/dev
 
 clean:
 	rm -rf $(TMPDIR)
-	rm -rf dist
+	rm -rf dist docs/build
 	rm -rf .coverage htmlcov
 	find -name '__pycache__' -print0 | xargs -0 rm -rf
 	find -name '*.~*' -delete
 
 
-.PHONY: bootstrap test lint coverage clean snap
+.PHONY: bootstrap test lint coverage clean snap docs
diff --git a/docs/en/authentication.md b/docs/en/authentication.md
new file mode 100644
index 0000000..a6ce31e
--- /dev/null
+++ b/docs/en/authentication.md
@@ -0,0 +1,161 @@
+---
+title: Authentication
+---
+
+Authentication
+==============
+
+You will require a valid Ubuntu SSO user to authenticate, and that user
+must have been configured as an admin in the snapstore.admin tool, e.g.
+
+    snapstore.admin add-admin [e-mail]
+
+The snap store uses macaroons for authentication, which are a kind of bearer
+token that can be constrained and that can be authorized by third-party
+services.  We strongly recommend using
+[pymacaroons](https://github.com/ecordell/pymacaroons) or
+[libmacaroons](https://github.com/rescrv/libmacaroons) to work with these
+tokens.
+
+If you want to understand more about how macaroons work, refer to the [original
+paper](https://research.google.com/pubs/pub41892.html).
+
+
+To login, you must first get a root macaroon from the snap store proxy,
+then discharge (verify) that macaroon with Ubuntu SSO
+(https://login.ubuntu.com/).
+
+
+Root Macaroon
+-------------
+
+To get a root macaroon:
+
+```
+POST https://<store_url>/v2/auth/issue-store-admin
+```
+
+The response is simple and matches this JSON Schema:
+
+```json
+{
+    'type': 'object',
+    'properties': {
+        'macaroon': {'type': 'string'},
+    },
+    'required': ['macaroon'],
+    'additionalProperties': False,
+}
+```
+
+This is your main authentication token, and should be stored persistently.
+
+
+Discharge Ubuntu SSO Caveat
+---------------------------
+
+The root macaroon contains a caveat that the user must have a valid
+Ubuntu SSO account. To prove that is the case, we need to discharge that
+caveat with Ubuntu SSO.
+
+You need to deserialize this root macaroon, and extract the caveat id
+with the location 'login.ubuntu.com'. For example, using pymacaroons:
+
+```python
+macaroon = pymacaroons.Macaroon.deserialize(root_macaroon)
+for caveat in macaroon.caveats:
+    if caveat.location == 'login.ubuntu.com':
+        return caveat.caveat_id
+```
+
+Then we need to discharge the caveat with Ubuntu SSO.
+
+    POST https://login.ubuntu.com/api/v2/tokens/discharge
+
+With request body populated with the user details and the caveat id.
+Ubuntu SSO doesn't have JSON Schema, but the request body should have
+the form as follows:
+
+```json
+{
+    "email": ...,
+    "password": ...,
+    "otp": ..., # if user account has 2FA enabled
+    "caveat_id": ...,
+}
+```
+
+Response:
+
+```json
+{
+    "discharge_macaroon": "<serialized discharge>",
+}
+```
+
+Note: for more detailed responses from Ubuntu SSO, particularly handling
+invalid credentials and 2FA, see the  general 
+[Ubuntu SSO documentation for OAuth tokens](
+http://canonical-identity-provider.readthedocs.io/en/latest/resources/token.html),
+which is also used by the macaroon discharge endpoint.
+
+You will need to persist the raw root macaroon and the raw discharge
+macaroon.  Together, these are your authentication.
+
+
+Request Authentication
+----------------------
+
+To authenticate a request, you must bind the discharge macaroon to the
+root macaroon, and send that as your value in an 'Authorization' HTTP
+header.
+
+For example, with pymacaroons:
+
+```python
+root = pymacaroon.Macaroon.deserialize(root_raw)
+discharge = pymacaroons.Macaroon.deserialize(discharge_raw)
+bound = root.prepare_for_request(discharge)
+header = 'Macaroon root="{}", discharge="{}"'.format(root_raw, bound.serialize())
+```
+
+Note: if your discharge macaroon has expired, it will be indicated by
+indicated by a 401 status code, and the header:
+
+```
+WWW-Authenticate: Macaroon needs_refresh=1
+```
+
+In this case you will need to refresh your discharge macaroon, described below,
+and retry the request.
+
+
+Refreshing the Discharge Macaroon
+---------------------------------
+
+Your discharge macaroon has an expiry, and needs refreshing with Ubuntu
+SSO periodically.
+
+To do so, simply:
+
+    POST https://login.ubuntu.com/api/v2/tokens/refresh
+
+With request body:
+
+```json
+{
+    "discharge_macaroon": "<discharge>"
+}
+```
+
+The response simply contains the new discharge macaroon.
+
+```json
+{
+    "discharge_macaroon": "<new discharge>",
+}
+```
+
+Update and persist this new discharge macaroon for later use.
+
+
diff --git a/docs/en/index.md b/docs/en/index.md
new file mode 100644
index 0000000..fe54667
--- /dev/null
+++ b/docs/en/index.md
@@ -0,0 +1,12 @@
+---
+title: Index
+---
+
+Snap Store Proxy API Documentation
+=================================
+
+This is the documentation for the snap store proxy, which allows you to override
+upstream revisions for specific snaps on your snap store proxy.
+
+* [Authentication](authentication.html)
+* [Overrides](overrides.html)
diff --git a/docs/en/overrides.md b/docs/en/overrides.md
new file mode 100644
index 0000000..cfbd628
--- /dev/null
+++ b/docs/en/overrides.md
@@ -0,0 +1,105 @@
+---
+title: Overrides
+---
+
+Overrides
+=========
+
+
+The Overrides API supports two operations: list overrides, and set overrides.
+
+All operations require an 'Authorization' header, as described in [Authentication](authentication.html).
+
+
+List Overrides
+--------------
+
+To list overrides for a snap name:
+
+```
+GET https://<store url>/v2/metadata/overrides/{snap_name}
+X-Ubuntu-Series: 16
+```
+
+Note the header.
+
+The response includes a list of any overrides for that snap. The format matches
+this JSON Schema:
+
+```json
+{
+    'type': 'object',
+    'properties': {
+        'overrides': {
+            'type': 'array',
+            'items': {
+                'type': 'object',
+                'properties': {
+                    'snap_id': {'type': 'string'},
+                    'snap_name': {'type': 'string'},
+                    'revision': {
+                        'type': 'integer',
+                        'minimum': 1,
+                    },
+                    'upstream_revision': {
+                        'type': ['integer', 'null'],
+                        'minimum': 1,
+                    },
+                    'channel': {'type': 'string'},
+                    'architecture': {'type': 'string'},
+                    'series': {'type': 'string'},
+                },
+                'required': [
+                    'snap_id', 'snap_name', 'revision', 'upstream_revision',
+                    'channel', 'architecture', 'series',
+                ],
+                'additionalProperties': False,
+            },
+        },
+    },
+    'required': ['overrides'],
+    'additionalProperties': False,
+}
+```
+
+
+Set Overrides
+-------------
+
+To set overrides:
+
+```
+POST https://<store url>/v2/metadata/overrides
+```
+
+with a request body listing the overrides for each snap/channel.
+
+The request format should match the following JSON Schema.
+
+```json
+{
+    'type': 'array',
+    'items': {
+        'type': 'object',
+        'properties': {
+            'snap_name': {'type': 'string'},
+            'revision': {
+                'type': ['integer', 'null'],
+                'minimum': 1,
+            },
+            'channel': {'type': 'string'},
+            'series': {'type': 'string'},
+        },
+        'required': ['snap_name', 'revision', 'channel', 'series'],
+        'additionalProperties': False,
+    },
+    'minItems': 1,
+}
+```
+
+To delete an override, simply set its revision field to null. The "series" field
+must be set to "16" currently.
+
+The response includes the results of the operation. The response format is the
+same as for listing overrides, except that "revision" can be null if an
+override was deleted.
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
new file mode 100644
index 0000000..0116991
--- /dev/null
+++ b/docs/metadata.yaml
@@ -0,0 +1,8 @@
+site_title: Snapstore Proxy API Documentation
+navigation:
+    - title: Index
+      location: en/index.md
+    - title: Authentication
+      location: en/authentication.md
+    - title: Overrides
+      location: en/overrides.md