Update API.md

API.md

@@ -56,6 +56,7 @@ Template variables
 ```json
 { "package_url": "https://packages.example.com/indexes/:package_name.json"
 , "package_index": "https://packages.example.com/index.json"
+, "pingback_url": "https://api.example.com/api/pingback@oauth3.org/:package_name?version=:package_version"
 }
 ```
 
@@ -71,6 +72,7 @@ Template variables
 ```json
 { "package_url": null
 , "package_index": null
+, "pingback_url": "https://api.example.com/api/pingback@oauth3.org/:package_name?version=:package_version"
 , "packages": [
   { "name": "hello@example.com"
   , "license": "Physical-Source-v2@licenses.org"
@@ -90,6 +92,11 @@ Template variables
 ] }
 ```
 
+**Note**: It is not expected that the package manage will directly query the publisher -
+a centralized caching service may be used.
+However, it is intended that a package manager *could* query the publisher, even if the
+publisher points back to a centralized cdn.
+
 Package Layout
 --------------
 
@@ -121,6 +128,31 @@ restarting the walnut server - for now at least
 Package APIs
 ------------
 
+Packages are intended to be functional, however, they allow for instantiation as
+a matter of not putting ourselves in a box and finding out later that it's very,
+very, very hard to open the box back up.
+
+`rest.js`:
+```
+module.exports.create = function (conf, deps, app) {
+  var API = require('./api.js');
+  var REST = {
+    hello: function (req, res/*, next*/) {
+      var promise = API.hello(deps, req.Models, req.oauth3/*, opts*/);
+      
+      app.handlePromise(req, res, promise, "[hello@example.com]");
+    }
+  }
+};
+```
+
+Special methods for `app`:
+
+### app.handlePromise(request, response, promise, message);
+
+`handlePromise` will respond to the request with the result of `promise` as JSON.
+If there is an error, it will include `message` in order to help you debug.
+
 ```
       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)