Update API.md

API.md

@@ -1,5 +1,6 @@
 * Bootstrap Initialization
-* Package Format
+* Package Discovery
+* Package Layout
 * Package APIs
 * RESTful API constraints
 
@@ -18,9 +19,94 @@ curl -X POST http://api.localhost.daplie.me:3000/api/walnut@daplie.com/init \
 
 From this point forward you can now interact with Walnut at that domain.
 
-Package Format
+OAuth3 Package Discovery
+-----------------
+
+Unlike most package systems such as npm (node.js), gem (ruby), pip (python), etc,
+which rely on a single, [centralized closed-source repository](https://github.com/npm/registry/issues/41),
+walnut packages use the OAuth3 Package Specification which allows for open and closed,
+public and private, free and paid packages, according to the desire of the publisher.
+
+In this model the name of a package is all that is necessary to install it from its publisher.
+
+Let's `hello@example.com` as an example:
+
+`hello@example.com` specifies that `hello` is a submodule of the `example.com` package.
+As you might guess, the publisher `example.com` is responsible for this package.
+
+`https://example.com/.well-known/packages@oauth3.org/` is the known location where package types can be discovered.
+
+Since we're using `walnut.js` which is published by daplie.com, we can find walnut packages at
+
+`https://example.com/.well-known/packages@oauth3.org/walnut.js@daplie.com.json`
+
+This file tells us where example.com publishes packages that adhere to the `walnut.js@daplie.com` package spec.
+(you can imagine that if walnut were to be implemented in ruby the ruby packages could be found at `walnut.rb@daplie.com`
+or if walnut were not protected by trademark and another company were to create a similar, but incompatible package
+system for it, it would be `walnut.go@acme.co` or some such)
+
+For publishers with a long list of packages you might find a URL using the template variable `:package_name` to describe
+where more information about a package can be found:
+
+```json
+{ "package_url": "https://packages.example.com/indexes/:package_name.json"
+, "package_index": "https://packages.example.com/index.json"
+}
+```
+
+For publishers with a short list of packages you might find that all of the packages are listed directly,
+using the template variables `:package_name`, `:package_version`, `:payment_token`.
+
+```json
+{ "package_url": null
+, "package_index": null
+, "packages": [
+  { "name": "hello@example.com"
+  , "license": "Physical-Source-v2@licenses.org"
+  , "requires_payment": true
+  , "payment_url": "https://author.tld/api/payments@oauth3.org/schemas/packages/walnut.js@daplie.com/:package_name"
+  , "zip_url": "https://cdn.tld/api/orders@cdn.tld/:package_name-:package_version.zip?authorization=:payment_token"
+  , "git_https_url":"https://git.cdn.tld/author.tld/:package_name.git#:package_version?authorization=:payment_token"
+  , "git_ssh_url":":payment_token@git.cdn.tld:author.tld/:package_name.git#:package_version"
+  }
+, { "name": "gizmo@example.com"
+  , "license": "MIT@licenses.org"
+  , "requires_payment": false
+  , "zip_url": "https://example.com/packages/:package_name-:package_version.zip"
+  , "git_https_url":"https://git.cdn.tld/author.tld/:package_name.git#:package_version"
+  , "git_ssh_url":"git@git.cdn.tld:author.tld/:package_name.git#:package_version"
+  }
+] }
+```
+
+Package Layout
 --------------
 
+Packages have data model, api, and RESTful components.
+
+```
+/srv/walnut/packages/rest/hello@example.com/
+  package.json
+  api.js
+  models.js
+  rest.js
+```
+
+Each package must be enabled on a per-domain basis.
+
+```
+/srv/walnut/packages/client-api-grants/provider.example.com
+  '''
+  hello@example.com
+  '''
+```
+
+When a package is enabled for `example.com` it becomes immediately available via https
+as `https://api.example.com/api/package@publisher.tld/`.
+
+Note: although hot-loading of packages is supported, reloading still requires
+restarting the walnut server - for now at least
+
 Package APIs
 ------------