From 2cace0b3ad202555e7270898ce31b2c42cdf45c0 Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@daplie.com>
Date: Wed, 2 Aug 2017 16:23:58 -0600
Subject: [PATCH] Update API.md

---
 API.md | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/API.md b/API.md
index d49ed0e..35295d2 100644
--- a/API.md
+++ b/API.md
@@ -1,16 +1,31 @@
+* Bootstrap Initialization
+* Package Format
+* Package APIs
+* RESTful API constraints
 
-API docs are here https://git.daplie.com/Daplie/com.example.hello
+Bootstrap Initialization
+--------------
 
+Before walnut is configured it starts up in a bootstrap mode with a single API exposed to set its primary domain.
 
 ```
-req.apiUrlPrefix => https://api.example.com/api/tld.domain.pkg
+# Set up with example.com as the primary domain
+curl -X POST http://api.localhost.daplie.me:3000/api/walnut@daplie.com/init \
+  -H 'X-Forwarded-Proto: https' \
+  -H 'Content-Type: application/json' \
+  -d '{ "domain": "example.com" }'
 ```
 
+From this point forward you can now interact with Walnut at that domain.
 
-Partial WALNUT API docs
-----------------
+Package Format
+--------------
+
+Package APIs
+------------
 
 ```
+      req.apiUrlPrefix => https://api.example.com/api/tld.domain.pkg
       req.experienceId      // the example.com part of https://example.com/foo (or example.com#foo if /foo is part of the app name)
       req.clientApiUri      // the api.example.com part of https://api.example.com/api/com.example.hello/kv/foo
       req.pkgId             // the com.example.hello part of https://api.example.com/api/com.example.hello/kv/foo
@@ -37,3 +52,21 @@ Partial WALNUT API docs
       req.Mandrill
       req.Mailchimp
 ```
+
+RESTful API Contstraints
+------------------------
+
+Walnut will reject requests to all domains and subdomains except those that begin with the subdomain `api`, `assets`, and `webhooks`.
+
+* `api` is for JSON APIs and must use JWT in HTTP Authorization headers for authentication
+  * secured by disallowing cookies
+  * secured by disallowing non-JSON form types
+  * secured by requiring authentication in header
+* `assets` is for large files and other blobs and must use JWT in Cookies for authentication
+  * warning: allows implicit authorization via cookies for hotlinking and the like
+  * secured by not exposing tokens when users copy-paste
+* `webhooks` is for 3rd-party API hooks and APIs with special requirements outside of the normal security model
+  * warning: these are insecure and should be used with caution, prudence, and wisdom
+  * JWT via query parameter
+  * urlencoded forms
+  * XML forms
\ No newline at end of file