walnut.js/API.md

* Bootstrap Initialization
* Package Format
* Package APIs
* RESTful API constraints

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

      req.getSiteStore().then(function (models) {
        req.Models = models;
      });

      req.Models.ComExampleHelloData.create(obj)
      req.Models.ComExampleHelloData.save(obj)
      req.Models.ComExampleHelloData.find(params)
      req.Models.ComExampleHelloData.destroy(objOrId)

      req.oauth3.accountIdx   // The system id of the account represented by the token

      req.getSiteConfig('com.example.hello').then(function (config) {
        // the com.example.hello section of /srv/walnut/etc/:domain/config.json
      });
      req.getSitePackageConfig
      req.getSiteMailer().then(function (mailer) {});

      // helper methods until we have agnostic means of doing the same / similar tasks
      req.Stripe
      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 protected access to 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

Bare and www domains are DISALLOWED from being served by Walnut.

This enables scalability of static sites as the static assets
are never on the same domain as generic APIs or authenticated assets.
It also enforces security by disallowing 1990s web vulnerabilities by default.