node-collection-json
Lightweight JavaScript client/server for easy data exchange and manipulation of objects in a Collection+JSON API. This library can be used in the browser and also server-side. It features, basic and advanced API querying capabilities. See below.
Client Usage
The calls to the API listed below are based on an imaginary API which has the following schema:
{
"collection": {
"version": "1.0",
"href": "http://plants-api/api/plants",
"links": [
{
"href": "http://plants-api/api",
"rel": "root"
},
{
"href": "http://plants-api/api/plants",
"rel": "plants"
}
],
"queries": [
{
"href": "http://plants-api/api/search",
"rel": "search",
"data": [
{
"name": "name",
"value": "",
"prompt": "The plant name"
}
]
}
],
"template": {
"data": [
{
"name": "name",
"value": "",
"prompt": "Plant Name"
},
{
"name": "type",
"value": "",
"prompt": "Plant type"
},
{
"name": "color",
"value": "",
"prompt": "Plant color"
}
]
}
}
}Query/Crawl the API
Query and crawl the Collection+JSON API.
import {CJClient} from 'node-collection-json';
// create client
let client = new CJClient("http://plants-api/api");
// get the collection
client.getCollection().then( collection => {
// follow a link
collection.getLinkByRel('plants').follow().then( collection => {
// display the data to console
console.log("FOLLOW LINK", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Crawl ERROR", JSON.stringify(collection.getJson(), null, 2));
});POST Data to the API
Post data to the API from the Template object.
import {CJClient} from 'node-collection-json';
// create client
let client = new CJClient("http://plants-api/api");
// get the collection
client.getCollection().then( collection => {
// follow a link
collection.getLinkByRel('plants').follow().then( collection => {
// get the template object and add data
collection.getTemplate()
.setData('type', 'fruit')
.setData('name', 'apple')
.setData('color', 'red');
// post the template object to the API
collection.post().then( collection => {
// display the data to console
console.log("CREATED DATA", JSON.stringify(collection.getJson(), null, 2));
}).catch( collection => {
// display the data to console
console.log("POST ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Follow Link ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Crawl ERROR", JSON.stringify(collection.getJson(), null, 2));
});Query/Update the API
Update data based on the Template object.
import {CJClient} from 'node-collection-json';
// create client
let client = new CJClient("http://plants-api/api");
// get the collection
client.getCollection().then( collection => {
// follow a link
collection.getLinkByRel('plants').follow().then( collection => {
// query the server
collection.getQueryByRel('search').setData('name', 'apple').query().then( collection => {
// import the first item to the template
let template = collection.getTemplate();
template.importItem(collection.getFirstItem());
// update the item
template.setData('type', 'fruit')
template.setData('name', 'banana')
template.setData('color', 'yellow');
// save the data
collection.put(collection.getFirstItem().getHref()).then( collection => {
// display the data to console
console.log("CREATED DATA", JSON.stringify(collection.getJson(), null, 2));
}).catch( collection => {
// display the data to console
console.log("Update ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Query ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Follow Link ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Crawl ERROR", JSON.stringify(collection.getJson(), null, 2));
});Query/Delete from API
Query/crawl the API and delete and Item.
import {CJClient} from 'node-collection-json';
// create client
let client = new CJClient("http://plants-api/api");
// get the collection
client.getCollection().then( collection => {
// follow a link
collection.getLinkByRel('plants').follow().then( collection => {
// query the server
collection.getQueryByRel('search').setData('name', 'banana').query().then( collection => {
// save the data
collection.getFirstItem().delete().then( collection => {
// display the data to console
console.log("DELETED DATA", JSON.stringify(collection.getJson(), null, 2));
}).catch( collection => {
// display the data to console
console.log("Update ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Query ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Follow Link ERROR", JSON.stringify(collection.getJson(), null, 2));
});
}).catch( collection => {
// display the data to console
console.log("Crawl ERROR", JSON.stringify(collection.getJson(), null, 2));
});Advanced Query Syntax
Complex/multiple API queries can be built and executed in the following manner.
// create the client and build the query
let client = new Client("http://api.test.com", {}, Client.API, new Cache(10000));
let queryBuilder = new QueryBuilder();
queryBuilder.item('orders').addParams({"id" : "54321"}).setIndex(0)
.item('customer').setIndex(0)
.item('addresses').search("zipCode", "12345");
// query the API
client.query(queryBuilder).then(function (collection) {
// output the street address
console.log(item.get("streetAddress"));
}).catch( collection => {
console.log("Crawl ERROR", JSON.stringify(collection.getJson(), null, 2));
});The previous example hops/crawls the API and fetches the desired data. This example refers to an imaginary API, so the parameters are invented for the purpose of explanation. The following processes are executed:
- The client goes to the root of the API: http://api.test.com and loads the data.
- It searches for a link with the rel tag "orders". When and if found, it appends the parameter: id=1234 to the link address. The setIndex(0) method, tells the client to select the first item and pass the collection to the next query. The following query link is built: http://api.test.com/orders?id=54321
- It searches the "customer" rel located in the item object follows the link and loads the data. Again, setIndex(0) fetches the first item object in the items array of the collection. The following query is built: http://api.test.com/customer/54321
- Finally, it fetches the "address" rel link from the customer item object, loads the data then searches the resulting item object for a key/value that matches "zipCode" and "12345". This final object is returned back to userland, where it can then be manipulated and displayed. The following query is built: http://api.test.com/addresses?customer=54321
Caching
Previous queries are cached in the client, so that extraneous queries for the same data sets are not executed again. This speeds up the response time. The cache accepts a time to live value (TTL) in seconds. This means, that after the TTL has been exceeded, the client will automatically re-query the data from the API.
The cache object is added to the constructor of Client:
// create cache object and add to constructor of client
let cache = new Cache();
let client = new Client("http://api.test.com", {}, Client.API, cache);If no TTL is set in the Cache constructor, the default value is set to two minutes. If caching is not desired, no caching object is required in the Client constructor.
// create cache object and set TTL to 5 minutes.
let client = new Client("http://api.test.com", {}, Client.API, new Cache(300));