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

Building a Node.js Clientfor Your REST+JSON API

Les Hazlewood @lhazlewoodCTO, 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

• 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 Resourcefunction InstanceResource(...) {...}util.inherits(InstanceResource, Resource);

anInstanceResource.save(function (err, saved) { ...});

anInstanceResource.delete(function (err) { ...});

Collection Resourcefunction CollectionResource(...) {...}util.inherits(CollectionResource, Resource);

aCollResource.each(function (item, callback) { ...}, function onCompletion(err) { ... });

aCollResource.eachSeriesaCollResource.mapaCollResource.filter... other async.js methods ...

Example: ApplicationListapplications.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 impacthttp://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

• 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 methodsClient client = Clients.builder() ... .build();

• Create multiple helper classesseparation 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

Resourcevar 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]; } }

module.exports = Resource;

InstanceResourcevar 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);};

Applicationvar 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 PatternString 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

Component Architectureaccount .save()

DataStore

CacheManager

DataStore

CacheManager

DataStore

CacheCacheCache

RequestExecutorCacheManager

DataStore

CacheCacheCache

RequestExecutor

AuthenticationStrategy

CacheManager

DataStore

RequestAuthenticator

CacheCacheCache

Component Architectureaccount

API Server

.save()

RequestExecutor

CacheManager

DataStore

CacheCacheCache

Component Architectureaccount

API Server

.save()

RequestExecutor ResourceFactory JSON Resource

CacheManager

DataStore

CacheCacheCache

Caching

Cachingvar cache = cacheManager.getCache(regionName);

cache.ttl //time to livecache.tti //time to idlecache.get(href, function(err, obj) { ...});

Cachingclient.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

Queriesaccount.getGroups(function(err,groups){...});//results in a request to://https://api.stormpath.com/v1/accounts/a1b2c3/groups

• What about query parameters?

Queriesaccount.getGroups( { name: ‘foo*’, description: ‘*test*’, orderBy: ‘name desc’, limit: 100 }, function onResult(err, groups) { ... });

//results in a request to:

https://api.stormpath.com/v1/accounts/a1b2c3/groups? name=foo*&description=*test*&orderBy=name%20desc&limit=100

Queries

Use a Fluent API!

Queriesaccount.getGroups().where() .name().startsWith(“foo”) .description().contains(“test”) .orderBy(“name”).desc() .limitTo(100));//results in a request to:

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 or Extensions module• One sub-module per plugin• Keep dependencies to a minimum

plugins/|- request/|- foo/

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: Promisesvar promise = account.getGroups();

promise.then(function() { //called on success}, function() { //called on error}, function() { //called during progress});

Lessons Learned: async.jsasync.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' });

$ 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

Software

The Emerging JSON/REST-based Identity Protocol Suite

Integrate Cloud Services with the REST/JSON Client

REST/JSON vs SOAP/XML · 2018-12-05 · REST/JSON vs SOAP/XML RECAP SEMINAR PowerBuilder User Regional Seminar – Barcelona, Spain Hotel NH Sants Barcelona DISCLAIMER This presentation

Delphi ORM SOA MVC SQL NoSQL JSON REST mORMot

SharePoint 2013 – REST, JSON and SharePoint Designer

Java at Fujitsu - Java Community Process · PDF fileSPECjbb benchmark Copyright 2016 ... (Java, PHP, Node.js, Ruby, ... Java API for JSON Processing(JSON-P) 1 Common Annotations for

Node.js and Browser Applications with ArcGIS REST JS€¦ · Node.js and browser applications with Ar cGIS REST JS Allison Davis Noah Mulnger slides: @araedavis @noahmulnger bit.ly/3aLDzaz

Json and Rest

Json and REST in the BizTalk World

Use Node.js to create a REST API

REST/JSON/CoreData Example Code - A Tour

R-Users Group JSON and ReST Introduction using Twitter

Designing a beautiful REST json api

REST and JSON in WCF

Oracle Database 12c JSON Document Store - NOCOUG Database 12c JSON Document Store New Features in 12.1.0.2 for Application Developers ... Oracle 12c as JSON Document Store Oracle Rest

JSON – AJAX - REST JavaScript Object Notation

REST Services with RabbitMQ, Spring Integration and Node.JS

Let’s talk about Computer Vision! - inovex...2018/02/19 · › Machine learning service with pre-trained models › JSON REST API + client libraries (C#, GO, Java, Node.js, PHP,

HPE ArubaOS-Switch REST API and JSON Schema Reference …HP-2530-48G-PoEP# show rest-interface REST Interface - Server Configuration REST Interface : Enabled REST Operational Status

ArcGIS GeoEvent Extension for Server: Best PracticesReceive JSON on a REST endpoint Receive Features on a REST endpoint Receive JSON on a WebSocket Receive RSS Receive Text from a