resource-client

Resource Client

Easily create api clients for your server side resources. Inspired by Angular Resource.

Usage

npm install resource-client --save

var resourceClient = require('resource-client');

var Product = resourceClient({
  url: 'http://www.mysite.com/api/products/:_id',
  headers: {
    'X-Secret-Token': 'ABCD1234'
  }
});

Product.query({isActive: true}, function(err, products) {
  product = products[0]
  product.name = 'apple'
  product.save()
});

Creating a Resource

resourceClient(options)

• options - default request options for this resource. You can use any option from the request module. There are a few key differences:
  • url - same as request url but can contain variables prefixed with a colon such as products/:name
  • json - set to true by default

var resourceClient = require('resource-client');

var Product = resourceClient({
  url: 'http://www.mysite.com/api/products/:_id',
  headers: {
    'X-Secret-Token': 'ABCD1234'
  }
})

Defining Resource Actions

Resource.action(name, options)

• name - name of action
• options - default request options for this action. Overrides defaults set for the resource. You can use any option from the request module. There are a couple extra options available:
  • url - same as request url but can contain variables prefixed with a colon such as products/:name
  • isArray - resource is an array. It will not populate variables in the url.
  • returnFirst - resource is an array. It will return the first result from the array

var resourceClient = require('resource-client');

var Product = resourceClient({
  url: 'http://www.mysite.com/api/products/:_id',
  headers: {
    'X-Secret-Token': 'ABCD1234'
  }
});

Product.action('query', {
  method: 'GET'
  isArray: true
});

Product.action('queryOne', {
  method: 'GET'
  isArray: true
  returnFirst: true
});

If the method is GET, you can use it as a class method:

Product.action('get', {
  method: 'GET'
});
// class method
Product.get({_id: 1234}, function (err, product) { ... })

If the method is PUT, POST, or DELETE, you can use it as both a class or an instance method:

Product.action('save', {
  method: 'POST'
});

// class method
Product.save({name: 'apple'}, function (err, product) { ... });

// instance method
product = new Product({name: 'apple'});
product.save(function(err) { ... });

Default Actions

Every new resource will come with these methods by default

• get - {method: 'GET'}
• query - {method: 'GET', isArray: true}
• queryOne - {method: 'GET', isArray: true, returnFirst: true}
• update - {method: 'PUT'}
• save - {method: 'POST'}
• remove - {method: 'DELETE'}

Additional per-request options

If you need to pass custom request options for an individual request, (for example, to identify a user with an authentication token), the action methods also take optional parameters, like so:

Product.save(
  {name: 'apple'},    // body
  {},                 // query params
  { headers: {} },    // extra options
  function (err, product) { ... }
 );

product = new Product({name: 'apple'});   // body comes from instance
product.save(
  {},                 // query params
  { headers: {} },    // extra options
  function(err) { ... }
);

Product.getById(urlParams, queryParams, otherOptions, callback);

Contributing

Please follow our Code of Conduct when contributing to this project.

$ git clone https://github.com/goodeggs/resource-client && cd resource-client
$ npm install
$ npm test

Module scaffold generated by generator-goodeggs-npm.