Add API description to README

authserver/README.md

@@ -1,4 +1,8 @@
-Setup:
+# Protospace lockout authorization server
+
+Provides an API to the web client and web server to serve tool data and authenticate users on tools.
+
+## Setup
 
 ```
 $ virtualenv -p python3 env
@@ -8,3 +12,124 @@ $ . env/bin/activate
 (env) $ python manage.py createsuperuser --email admin@example.com --username admin
 (env) $ python manage.py runserver
 ```
+
+## API
+
+The API is RESTful and returns hyperlinked json data.
+
+### For anonymous users
+
+#### GET `/tooldata`
+
+Returns all the info about the shop and its tools. Tools are split into categories.
+
+Example response:
+
+```
+{
+    "categories": [
+        {
+            "url": "http://127.0.0.1:8000/category/wood-shop/",
+            "tools": [
+                {
+                    "url": "http://127.0.0.1:8000/tool/table-saw/",
+                    "category": "http://127.0.0.1:8000/category/wood-shop/",
+                    "name": "Table Saw",
+                    "slug": "table-saw",
+                    "info": "scary tool",
+                    "wiki_id": 123,
+                    "photo": "http://127.0.0.1:8000/media/floodgf.jpg"
+                },
+                {
+                    "url": "http://127.0.0.1:8000/tool/jointer/",
+                    "category": "http://127.0.0.1:8000/category/wood-shop/",
+                    "name": "Jointer",
+                    "slug": "jointer",
+                    "info": "goes buzz buzz",
+                    "wiki_id": 1,
+                    "photo": "http://127.0.0.1:8000/media/uq4ldzsp4bu01.jpg"
+                }
+            ],
+            "name": "Wood Shop",
+            "slug": "wood-shop",
+            "info": "protospace wood shop",
+            "photo": "http://127.0.0.1:8000/media/photo_2018-05-06_13-26-59.jpg"
+        },
+        {
+            "url": "http://127.0.0.1:8000/category/metal-shop/",
+            "tools": [
+                {
+                    "url": "http://127.0.0.1:8000/tool/metal-lathe/",
+                    "category": "http://127.0.0.1:8000/category/metal-shop/",
+                    "name": "Metal Lathe",
+                    "slug": "metal-lathe",
+                    "info": "spins fast",
+                    "wiki_id": 42,
+                    "photo": "http://127.0.0.1:8000/media/intro-metal-shop-vali-steele-97.jpeg"
+                }
+            ],
+            "name": "Metal Shop",
+            "slug": "metal-shop",
+            "info": "protospace metal shop",
+            "photo": "http://127.0.0.1:8000/media/photo_2018-05-08_17-57-02.jpg"
+        }
+    ]
+}
+```
+
+### For authenticated users
+
+#### GET `/user`
+
+Returns info about the logged in user, including which tools they are authorized on. Note the top-level array (a quirk of django-rest-framework).
+
+Example response:
+
+```
+[
+    {
+        "username": "admin",
+        "profile": {
+            "url": "http://127.0.0.1:8000/profile/1/",
+            "user": "admin",
+            "authorized_tools": [
+                "table-saw",
+                "jointer"
+            ],
+            "lockout_admin": true
+        }
+    }
+]
+```
+
+### For lockout admins
+
+Ensure images are 1280x1280 px large. Slugs should be lowercase and one word (repace spaces with hyphens).
+
+#### GET, POST `/tool`
+
+Get a list of tools, or post a new tool to the database.
+
+#### GET, PUT, DELETE `/tool/[slug]`
+
+Get a specific tool, modify or delete an existing one.
+
+#### GET, POST `/category`
+
+Get a list of categories, or post a new category to the database.
+
+#### GET, PUT, DELETE `/category/[slug]`
+
+Get a specific category, modify or delete an existing one.
+
+Note: you can only delete a category that has no tools.
+
+#### GET `/profile`
+
+Get a list of all profiles.
+
+#### GET, PUT `/profile/[id]`
+
+Get a specific profile, or modify an existing one.
+
+Here you can authorize users on tools or make them another lockout admin.