78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
* 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. |