gistfile1.md

extension interface for the rendr apiProxy / dataAdapter

Currently, when custom behavior for the apiProxy is required, users have to copy the whole apiProxy to make custom changes. While some custom behavior can be placed in the dataAdapter, this does not allow more complex things, which is why we proposed adding cookie handling to the core apiProxy where it does not belong (see #232). This proposal tries to make both the apiProxy and dataAdapter extensible using small, reusable modules. Once rendr supports configuring different data adapters per configured API, this will allow to enable a extension module for all configured APIs by setting it on the ApiProxy or just a specific API by setting it on a DataAdapter.

This would require two extension points: One before the DataAdapter is used to make the request and one when it receives the response. We propose implementing this using two events which will be emitted by both the apiProxy and the dataAdapter(s):

• one event sent before issuing the request to the API, where the handler function can access the request objects (and possible also the responseToClient though I'm not sure if that makes sense):

  apiProxy.on('before', function addXForwardedForHeader(requestFromClient, requestToApi) {
       requestToApi.headers['X-Forwarded-For'] = ...
       // ...
  });
  

• one event when the response is received, with access to the response objects (and possible also the request objects, though I'm not sure if that makes sense):

  apiProxy.on('after', function copyCookiesFromApiResToClientRes(responseToClient, responseFromApi) {
    //...
  })
  

• a shortcut for including extensions that use both before and after hooks:

  apiProxy.use(passthroughCookies))
  // equivalent to:
  //   apiProxy.on('before', passthroughCookies.before ))
  //   apiProxy.on('after', passthroughCookies.after ))