#ee-soa-request
Application internal, protocol independent request/response implementation.
npm install ee-soa-request
var Request = require('ee-soa-request');
var myRequest = new Request();
var myReadRequest = new Request.ReadRequest();
Some of the important methods the read request object provides (incomplete):
// needs a callback to support asynchronous loading in the future
request.getContent(callback)
request.setContent(content)
request.setContentType(type)
request.getContentType()
The type of the request is based on the action code (for crud/rest mapping, analogous to http methods).
request.setAction(actionCode)
request.getAction()
request.isOfType(actionCode)
request.isReadRequest()
request.isCreateRequest()
request.isUpdateRequest()
request.isDeleteRequest()
request.isWriteRequest()
request.isInfoRequest()
request.isOptionsRequest()
A request is often created to query specific relations/models.
request.getCollection() :string
// alias
request.getController() :string
request.setCollection(collection:string)
request.queriesCollection() :boolean
request.getResourceId()
request.setResourceId(id:mixed)
request.hasResourceId()
request.hasRelatedTo()
request.getRelatedTo() : {model:string, id: mixed}
request.setRelatedTo(model, id)
request.getVersion() // api version
request.setVersion(version)
request.versionCompare(version) // 0 if equal, -1 if request version is smaller, 1 if bigger
request.addFormat(type, subtype) // e.g. 'application' 'json'
request.acceptsFormat(type, subtype)
request.setLanguages(languageArray)
request.getLanguages()
request.acceptsLanguage(languageString)
request.hasRange()
request.setRange(from, to)
request.getRange(): {from:mixed, to:mixed} // Ranges (from, to) are set to null if not present
// filters
// projections
// orderings
// orderings
The following request types are defined (based on the http verbs for rest interfaces), please use them and not the generic Request
.
- DeleteRequest DELETE
- InfoRequest HEAD
- CreateRequest PUT
- OptionsRequest OPTIONS
- ReadRequest GET
- UpdateRequest PATCH
- WriteRequest POST
The different types of requests implement a dispatch
method which takes a handler as its argument (the request performs a so called double-dispatch, this allows you to easily handle the request without knowing its type upfront). A handler is described by the following set of methods (to say it in terms of duck-typing)
var handler = {
handleCreateRequest: function(req, options){ ... }
handleDeleteRequest: function(req, options){ ... }
handleInfoRequest: function(req, options){ ... }
handleOptionsRequest: function(req, options){ ... }
handleReadRequest: function(req, options){ ... }
handleUpdateRequest: function(req, options){ ... }
handleWriteRequest: function(req, options){ ... }
}
You can use the options parameter to pass in additional data e.g. the request if you want to send the your data directly from your handler. See the following (rudimentary) example for a read request:
var handler = {
handleReadRequest: function(req, options){
// list
var query = 'SELECT * FROM :collection:'
, params = {collection: req.getCollection()};
// listOne
if(req.hasResourceId()){
params['id'] = req.getResourceId();
query += 'WHERE `id`= :id:';
}
var data = this.performQuery(query, params);
options.response.send(options.response.OK, data);
}
};
request.dispatch(handler, {response: response});
Formats are the internal representation of the internet media types (currently not supporting parameters such as the encoding). All types of Request
objects provide easy accessors to preserve you from dealing with the internal data format.
Add a format to the current format collection of the request (type and subtype are strings
the asterisk represents the wildcard.
This method can be used to to check if a request accepts a specific response format based on the internet media type (type, subtype). It returns the priority of the passed format to allow your service or controller to check which formats are accepted, and which should be delivered (the relation is covariant
, so image/*
accepts image/jpg
but not the other way round). Lets consider an example for an simple image service:
// The accepted formats are image/jpg, application/*
// We can create jpgs and json
var acceptsJPG = request.acceptsFormat('image', 'jpg'),
acceptsJSON = request.acceptsFormat('application', 'json');
if(acceptsJPG === false && acceptsJSON === false){
return this.sendUnsatisfiableResponse();
}
if(acceptsJPEG > acceptsJSON){
return this.sendImageResponse();
}
return this.sendJSONResponse();
One can immediately see, that we need the priority to be able to distinguish which response to send (because the request accepts both). More formats can easily be checked in a loop.