Update API.md

This commit is contained in:
AJ ONeal 2017-08-02 16:23:58 -06:00
parent 7e98e02df5
commit 2cace0b3ad
1 changed files with 37 additions and 4 deletions

49
API.md
View File

@ -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.
```
# 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.
Package Format
--------------
Package APIs
------------
```
req.apiUrlPrefix => https://api.example.com/api/tld.domain.pkg
```
Partial WALNUT API docs
----------------
```
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