geddy-rest
v0.0.8
Published
RESTfull api for Geddy
Downloads
25
Readme
GeddyJs REST Helper
Use this simple library to avoid code repetition for Controllers REST actions. With one single line, you provide all the methods you need for your controller, in order to have a fully REST api.
It is made to be used with GeddyJs.
Instalation
- Run:
npm install --save geddy-rest
- Add the folowing line inside your controller:
require('geddy-test').RESTify(this, MyModel);
- Add the folowing line inside
/config/routes.js
:
require('geddy-test').route(router, 'mymodel');
- You are done, and you can access trough:
GET /:model ---> Find All
GET /:model/:id ---> Find First
POST /:model/:id ---> Create
PUT /:model/:id ---> Update
DELETE /:model/:id ---> Destroy
If you want named
paths with GET
method, read below.
Nested findings
Imagine the folowing situation: User
hasMany
Photos
. If you need to read the User photos, you would need to go to an endpoint like GET /photos?userId=<theUserId>
, after getting the user information in GET /users/<theUserId>
.
With that in mind, I made a simple helper that allows you to do even more with Geddy. This situation will become GET /users/<theUserId>/photos
, in a really simple way.
We present you, nested associations with REST:
// Add this to your config/routes.js to allow use of nested findings
require('geddy-test').RestApi.route(router, 'users', {
find: {
// Enables Nested finding route
nested: true
}
});
// User Controller
// We are nesting the model method 'getPhotos' as 'photos'
require('geddy-test').RESTify(this, MyModel, {
find: {
nested: {
photos: 'getPhotos'
}
}
});
// You can even nest multiple actions, and provide a custom callback like:
function specialMethod(cb){
// Send back data to be replaced
cb({custom: 'data', to: 'be', shown: true});
}
require('geddy-test').RESTify(this, MyModel, {
find: {
nested: {
photos: 'getPhotos',
friends: 'getFriends',
address: 'getAddress',
special: specialMethod
}
}
});
The example above would generate the folowing routes:
GET /users/:id/photos -> find then getPhotos
GET /users/:id/friends -> find then getFriends
GET /users/:id/address -> find then getAddress
GET /users/:id/special -> find then run specialMethod
Using it as a middleware
You can also use those methods for your own purpose. Look at some examples:
var Users = function (){
// Inject methods into controller
require('geddy-rest').RESTify(this, geddy.model.User);
// Should route to: /users/:id/resume
this.resume = function (req, res, params){
// Execute custom find method
this.find(req, res, params, function afterFind(err, model, cb){
var data = {
userName: model.name,
userFriendsCount: model.getFriends().length
};
// Continue with it...
return cb(data);
// Or render it yourself
respond(data);
});
}
}
Advanced usage
RESTify(controller, model, opts)
Restify creates methods inside your given
controller
. It uses themodel
to create/find/delete/update.You can also assign some options:
opts.[create|find|update|destroy]
: [false
|Object
] If set to false, will not generate the method.example:
// Only enables find method RESTify(this, MyModel, { create: false, destroy: false, update: false, });
opts.[create|find|update|destroy].action
:String
Use this to change the desired method to be saved. You can, for example, generate it and use it the way you want:RESTify(this, MyModel, { find: { action: 'myFindAction' } }); this.find = function (req, res, params){ // Do whatever you want.... var a = 2*9; // Delegate it to the REST find method this.myFindAction(req, res, params); }
opts.[create|find|update|destroy].beforeRender
:function
Use this property to receive actions just before rendering the data. You can either render it yourself (just don't call the
next
function), or process something before rendering and delegate it to the REST action egain:this._checkDbFirst = function (err, models, next){ // You render the content here. Just don't call next. respond(models); // But if you do, pass the models to render next(models); } RESTify(this, MyModel, { create: { action: 'find', beforeRender: this._checkDbFirst } });
opts.find.nested
:Object
Put each nested method as the key, and the callback as the value. (Read above for more info);
GeddyJs is a well tought Framework. If you need to perform actions either
before
orafter
a call to the REST endpoint, use the methods.before
and.after
:// Calls prepareThings before find and create this.before(prepareThings, {only: ['find', 'create']}); // Calls finishThingsUp after update and destroy this.after(finishThingsUp, {only: ['update', 'destroy']});
route(Router, ModelName, opts)
This will generate routes acordingly to your needs. It should be placed inside
/config/routes.js
.If you need to alter the
default routes
, orHTTP methods
you can access it exacly like theRESTify
method:// Change the default route of 'find' to 'get' // Change the destroy method to 'GET' // Disables update route route(router, MyModelName, { find: { action: 'get' }, destroy: { method: 'GET' }, update: false });
One last usefull option, is the
opts.strict
, which defaults is set totrue
.If set to false, will generate PATHS to facilitate your life (during development?):
GET /:model/find GET /:model/find/:id GET /:model/create GET /:model/destroy/:id GET /:model/update/:id