Build a Node.js Client for Your REST+JSON API

Building a Node.js Client
for Your REST+JSON API
Les Hazlewood @lhazlewood
CTO, Stormpath stormpath.com

.com
• User Management and Authentication
API
• Security for your applications
• User security workflows
• Security best practices
• Developer tools, SDKs, libraries

Overview
• Resources
• Public / Private API
• Proxy Design
• Active Record
• Fluent API
• Configuration
• Caching
• Authentication
• Pluggability
• Lessons Learned

HATEOAS
• Hypermedia
• As
• The
• Engine
• Of
• Application
• State
Learn more at Stormpath.com

Resources

Resources
• Nouns, not verbs
• Coarse-grained, not fine-grained
• Support many use cases
• Globally unique HREF

Collection Resource
• Example:
/applications
• First class resource w/ own properties:
• offset
• limit
• items
• first, next, previous, last
• etc
• items contains instance resources

Instance Resource
• Example:
/applications/8sZxUoExA30mP74
• Child of a collection
• RUD (no Create - done via parent collection)

Translating to Code

Resource
var util = require('util');
function Resource(...) { ... }
util.inherits(Resource, Object);
someResource.href

Instance Resource
function InstanceResource(...) {...}
util.inherits(InstanceResource, Resource);
anInstanceResource.save(function (err, saved) {
...
});
anInstanceResource.delete(function (err) {
...
});

Collection Resource
function CollectionResource(...) {...}
util.inherits(CollectionResource, Resource);
aCollResource.each(function (item, callback) {
...
}, function onCompletion(err) {
...
});
aCollResource.eachSeries
aCollResource.map
aCollResource.filter
... other async.js methods ...

Example: ApplicationList
applications.each(function(app, callback){
console.log(app);
callback();
}, function finished(err) {
if (err) console.log(„Error: „ + err);
});

Design!

Encapsulation
• Public API
• Internal/Private Implementations
• Extensions
• Allows for change w/ minimal impact
http://semver.org

Encapsulation in practice
• Use an underscore prefix: _
• Super clear code comments:
mark @public or @private
• Public API docs: don’t display private
classes/methods/functions

Public API

Public API
• All non-@private functions/vars
• Builder methods (method chaining)
• Object literals (config) is public too!

Public prototypical OO Classes
• Client
• ApiKey
• Application
• Directory
• Account
• Group
• etc

Classes with static helper methods
Client client = Clients.builder()
...
.build();
• Create multiple helper classes
separation of concerns

Builder methods (method chaining)
client.getApplications()
.where(name).startsWith(„*foo‟)
.orderBy(name).asc()
.limit(10)
.execute(function (err, apps){
...
});
clients.getApplications()  ApplicationRequestBuilder
Single Responsibility Principle!

Private API
• Implementations + SPI interfaces
• Builder implementations
• Implementation Plugins

Resource Implementations
• Create a base Resource class:
• Property manipulation methods
• Dirty checking
• Reference to DataStore
• Lazy Loading
• Create base InstanceResource and CollectionResource
implementations
• Extend from InstanceResource or CollectionResource

Resource
var utils = require(‟utils');
function Resource(data, dataStore) {
var DataStore = require('../ds/DataStore');
if (!dataStore && data instanceof DataStore){
dataStore = data;
data = null;
}
data = data || {};
for (var key in data) {
if (data.hasOwnProperty(key)) {
this[key] = data[key];
}
}
var ds = null; //private var, not enumerable
Object.defineProperty(this, 'dataStore', {
get: function getDataStore() {
return ds;
},
set: function setDataStore(dataStore) {
ds = dataStore;
}
});
if (dataStore) {
this.dataStore = dataStore;
}
}
utils.inherits(Resource, Object);
module.exports = Resource;

InstanceResource
var utils = require(„utils');
var Resource = require('./Resource');
function InstanceResource() {
InstanceResource.super_.apply(this, arguments);
}
utils.inherits(InstanceResource, Resource);
InstanceResource.prototype.save = function
saveResource(callback) {
this.dataStore.saveResource(this, callback);
};
InstanceResource.prototype.delete = function
deleteResource(callback) {
this.dataStore.deleteResource(this, callback);
};

Application
var utils = require(„utils');
var InstanceResource = require('./InstanceResource');
function Application() {
Application.super_.apply(this, arguments);
}
utils.inherits(Application, InstanceResource);
Application.prototype.getAccounts = function
getApplicationAccounts(/* [options,] callback */) {
var self = this;
var args = Array.prototype.slice.call(arguments);
var callback = args.pop();
var options = (args.length > 0) ? args.shift() : null;
return self.dataStore.getResource(self.accounts.href, options,
require('./Account'), callback);
};

Usage Paradigm

Account JSON Resource
{
“href”: “https://api.stormpath.com/v1/accounts/x7y8z9”,
“givenName”: “Tony”,
“surname”: “Stark”,
…,
“directory”: {
“href”:
“https://api.stormpath.com/v1/directories/g4h5i6”
}
}

Proxy Pattern
String href = “https://api.stormpath.com/v1/....”;
client.getAccount(href, function(err, acct) {
if (err) throw err;
account.getDirectory(function(err, dir) {
if (err) throw err;
console.log(dir);
});
});

Proxy Pattern

Component Architecture

account .save()

account .save()
DataStore

account .save()
Cache
Manager
DataStore

account .save()
Cache
Manager
DataStore
Cache
Cache
Cache

account .save()
RequestExecutorCache
Manager
DataStore
Cache
Cache
Cache

account .save()
RequestExecutor
Authentication
Strategy
Cache
Manager
DataStore
Request
Authenticator
Cache
Cache
Cache

account
API Server
.save()
RequestExecutor
Authentication
Strategy
Cache
Manager
DataStore
Request
Authenticator
Cache
Cache
Cache

account
API Server
.save()
RequestExecutor ResourceFactory
JSON  Resource
Authentication
Strategy
Cache
Manager
DataStore
Request
Authenticator
Cache
Cache
Cache

Caching

Caching
var cache = cacheManager.getCache(regionName);
cache.ttl //time to live
cache.tti //time to idle
cache.get(href, function(err, obj) {
...
});

Caching
client.getAccount(href, function(err, acct) {...});
// in the DataStore:
var cache = cacheManager.getCache(„accounts‟);
cache.get(href, function(err, entry) {
if (err) return callback(err);
if (entry) {
... omitted for brevity ...
return callback(entry.value);
}
//otherwise, cache miss – execute a request:
requestExecutor.get(href, function(err, body) {
//1. cache body
//2. convert to Resource instance
//3. invoke callback w/ instance
}
}

Queries

Queries
account.getGroups(function(err,groups){...});
//results in a request to:
//https://api.stormpath.com/v1/accounts/a1b2c3/groups
• What about query parameters?

Queries
account.getGroups(
{
name: „foo*‟,
description: „*test*‟,
orderBy: „name desc‟,
limit: 100
},
function onResult(err, groups) {
...
}
);
https://api.stormpath.com/v1/accounts/a1b2c3/groups?
name=foo*&description=*test*&orderBy=name%20desc&limit=100

Queries
Use a Fluent API!

Queries
account.getGroups().where()
.name().startsWith(“foo”)
.description().contains(“test”)
.orderBy(“name”).desc()
.limitTo(100)
);
https://api.stormpath.com/v1/accounts/a1b2c3/groups?
name=foo*&description=*test*&orderBy=name%20desc&limit=100

Authentication

Authentication
• Favor a digest algorithm over HTTP Basic
• Prevents Man-in-the-Middle attacks (SSL won’t guarantee
this!)
• Also support Basic for environments that require it (Dammit
Google!)
• ONLY use Basic over SSL
• Represent this as an AuthenticationScheme to your Client /
RequestExecutor

Authentication
• AuthenticationScheme.SAUTHC1
• AuthenticationScheme.BASIC
• AuthenticationScheme.OAUTH10a
• ... etc ...
Client client = new stormpath.Client({
//defaults to sauthc1
authcScheme: „basic‟
});
Client/RequestExecutor uses a Sauthc1RequestAuthenticator or
BasicRequestAuthenticator or OAuth10aRequestAuthenticator, etc.

Plugins

Plugins
• Plugins or Extensions module
• One sub-module per plugin
• Keep dependencies to a minimum
plugins/
|- request/
|- foo/

Lessons Learned

Lessons Learned
• Recursive caching if you support resource
expansion
• Dirty checking logic is not too hard, but it does
add complexity. Start off without it.

Lessons Learned: Promises
var promise = account.getGroups();
promise.then(function() {
//called on success
}, function() {
//called on error
}, function() {
//called during progress
});

Lessons Learned: async.js
async.waterfall([
function(callback){
callback(null, 'one', 'two');
},
function(arg1, arg2, callback){
// arg1 now equals 'one' and arg2 now equals 'two'
callback(null, 'three');
},
function(arg1, callback){
// arg1 now equals 'three'
callback(null, 'done');
}
], function (err, result) {
// result now equals 'done'
});

Code
$ git clone
https://github.com/stormpath/stormpath-sdk-
node.git
$ cd stormpath-sdk-node
$ npm install
$ grunt

Thank You!
• les@stormpath.com
• Twitter: @lhazlewood
• http://www.stormpath.com

Build a Node.js Client for Your REST+JSON API

More Related Content

What's hot

Viewers also liked

Similar to Build a Node.js Client for Your REST+JSON API

Recently uploaded

Build a Node.js Client for Your REST+JSON API