Update API.md

This commit is contained in:
AJ ONeal 2017-08-02 17:59:41 -06:00
parent 25df88e297
commit 9a0222c991
1 changed files with 32 additions and 0 deletions

32
API.md
View File

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