Home

oslc-client: A JavaScript Node.js Module for OSLC

oslc-client is an OSLC4JS sub-project to develop a JavaScript Node.js module supporting OSLC client and server development. The client API exposes the OSLC core and domain capabilities through a simple JavaScript API on the OSLC REST services. The same API may also be used as an abstract implementation of a server supporting OSLC core capabilities and domains. An Express.js middleware component could be used to implement the OSLC REST services that delegate to this API which can then be adapted to existing data sources, services and OSLC domains.

oslc-client exploits the dynamic and asynchronous capabilities of JavaScript and Node.js to build and API that can easily adapt to any OSLC domain, extensions to domains, and/or integrations between domains.

Governance

oslc-client, like all the OSLC4JS projects is Open Source software using the Apache v2 license.

• OSLC/oslc-client GitHub Project: provides source code management
• Wiki This Wiki: provides project design and detailed documentation
• Track & Plan IBM DevOps Services Track & Plan: used for project planning and issue management
• npm package The Node module is published as an npm package, install with npm install oslc-client

Motivation

OSLC defines a set of REST services layered on top of W3C Linked Data Platform (LDP). Although the Node.js http, connect or express packages could be used to develop OSLC client applications that directly access the REST services, some client developers may wish to have a more logical API that exposes OSLC capabilities and interactions in a simpler, higher-level, and possibly less error prone way. This is the goal of the oslc-client API. Rather than dealing directly with HTTP headers, requests, creating raw entity request bodies, parsing raw entity response bodies, or dealing directly with OAuth authentication, a client developer can simply make logical API functions that use simple JavaScript (JSON) arguments.

For example, the following code show how to use the oslc-client API to connect to an OSLC Change Management server, login, use a particular project area, read and update a change request.

async.series([
	function connect(callback) {server.connect(userName, password, callback);},
	function use(callback) {server.use(providerContainerName, callback);},
	function read(callback) {
		server.read(changeRequestID, function(err, result) {
			if (!err) {
				changeRequest = result;
				console.log('Got Change Request: ')
				console.log(changeRequest);
			}
			callback(err, changeRequest);
		});
	},
	function update(callback) {
		changeRequest.description = changeRequest.description + new Date();
		server.update(changeRequest, function (err) {
			if (!err) console.log('Updated: '+changeRequest.id);			
			callback(err);
		});
	},
	function cleanup(callback) {
		server.disconnect();
		console.log('Done');
		callback(null);
	}
]);

Because all of the oslc-client function calls involve one or more HTTP requests, they are all written to be asynchronous calls requiring a callback function. The design of the API is based on a consistent format for the callback functions. Each callback function is essentially supporting an asynchronous return of an error status and zero or more return values.

The async package (or some other way of sequencing asynchronous functions) is required to sequence some of the functions. In the example above, the client has to connect to a server and use a root container before it can read or write any resources. Similarly it is often necessary to read a resource before it is updated in order to get the current values.

Notice that since oslc-client callback function signatures are consistent with the async package, the same callback functions may be useful for async or oslc-client API functions, depending on the need. For example, the callback for the oslc-client connect function is the same as the callback for the async connect function used to sequence the functions. When the connection has completed, the server.connect function implementation callback can be used directly for the async connect callback, eliminating the need to create a new wrapper callback function.

Of course the OSLC REST services are still available to use directly. So if there's something you need to do that either isn't provided by the client API, or is inconvenient for some reason, then by all means create the HTTP request and handle the raw response directly.

The rest of this Wiki explores some of the design issues and other considerations that had to be addressed in developing the oslc-client API, and provides additional documentation on how to use the API to develop client applications. Additional sample code is in the oslc-client/examples folder on GitHub.

Developing oslc-client.js

Jazz Authentication in JavaScript

Using RDF in JavaScript and Node.js

Using JSON-LD instead of RDF Directly

A Sample OSLC Change Management Client App