notes on APIv3 and REST
APIv3.rest: goals tweaked using input colleagues

dmajda and cornelius.
APIv3: Means section expanded a bit
APIv3: added Specifications section
APIv3: added Further Reading section
e2e test for GET /user/appliances/:app/configuration
lib/lo/http#request handles binary data

does not assume strings, uses and returns Buffers instead.

the collection of the whole response body is convenient
for current simplistic clients but completely out of place
in library code.
if the library implementation uses streams, it makes no sense
to buffer instead of *exposing* streams.

using Buffers for image downloads would be catastrophic
for instance.
initial support for non-xml responses...

such as backgrounds, logos, packages, overlay files...

xml2js has no interface for parsing streams :( even though
the underlying sax has one! :((

the plan is to either add streaming to xml2js, or rip it out
and use sax directly.
GET /user/appliances/:app/configuration/logo

the e2e test is extremely weak.
lib/lo/common#api uses response body handler table

manages the complexity of the rpc function callback.
lib/lo/http#request does not buffer data...

... passes the whole response to clients.

this allows streaming data from server if necessary.
response handler for xml buffers data itself, as is
necessary for xml2js::parse.
xml response processing goes into lib/lo/xml

lib/lo/admin, lib/lo/user now export the transforms maps
to keep them testable; until now they exported the result
of common.transform.
lib/lo/{admin,user}#transforms ready for requests

these maps were coupled with response processing, and unless
i want to keep the input as server-defined xml, which i don't,
they also need to define input conversion from json to xml.
not to mention non-xml payloads.
lib/lo/common#rpc complains about missing api args

previously it went ahead with "undefined".
lib/lo/common#rpc: 2x extract function

parameter substitution into the url + query string build.
lib/lo/common#rpc needs the transforms map

it's the best place to generate request headers and bodies
from inputs, and lib/lo/{admin,user}#transforms is the
best place to define the rules.