3.0 KiB
3.0 KiB
- 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.