Integrating REST Services

The Oracle JET framework is designed to work with any web service that returns data in the form of JSON objects. Because the content of JSON objects can vary widely from service type, the application developer is responsible for examining the JSON object’s content and defining the ViewModel appropriately.

Topics:

About Oracle JET Framework Support for Integrating REST Services

The Model and Collection classes provide native support for mapping JSON objects obtained from REST web services to Knockout observables. The oj.Collection.url property specifies the path to the web service data.

oj.Collection.extend({url:"http://myserver/departments",...})

Model objects also include the url property. By default, this is set to the model ID appended to the oj.Collection.url property: http://myserver/departments/modelID.

To override the default path set by the Collection object, set the oj.model.urlRoot property, and the application will use the url.Root/modelID as the path to the data.

The Oracle JET framework also provides three ways to customize the AJAX requests that Oracle JET makes when accessing REST services through the Common Model.

  • Pass custom AJAX options in Common Model CRUD API calls.

  • Supply a customURL callback function.

  • Replace the oj.sync or oj.ajax functions.

Passing Custom AJAX Options in Common Model CRUD API calls

Use this method if the default URL behavior is acceptable, but your application needs to pass custom properties such as headers to the REST server.

To customize the AJAX options, add property/value pairs to the options argument of the oj.Collection.create(create), oj.Collection.fetch(read),oj.Model.save(update), and oj.Model.destroy(delete) functions.

The following code example shows how an application could pass in a custom header when doing a read from the REST service.

myOjCollection.fetch(
                     {headers:{my-custom-header:"header-value"},
                      beforeSend: myBeforeSendCallbackFunc,
                      success:function(collection){
                     }});

Supplying a customURL Callback Function

If you need to customize the URL or AJAX behavior, set the oj.Collection.customURL property to a user-defined callback function when defining the collection.

function myCustomFunction(operation, collection, options) {
...
}
var myCollection = oj.Collection.extend({customURL:myCustomFunction,...})

The callback function should include the following parameters which are passed to it by default:

  • operation: create, read, update, patch, or delete

  • collection: The oj.Model or oj.Collection object requesting the operation

  • options: Information relevant to the operation

Typical options include:

  • recordID: Id of the record involved in the operation

  • fetchSize: The number of records to return; returns all if not set

  • startIndex: Starting record number of the data set

  • fromID: Retrieve records starting with the record with the given unique ID

  • since: Retrieve records with timestamps after the given timestamp

  • until: Retrieve records with timestamps up to the given timestamp

  • sort: Field or fields by which to sort

  • sortDir: Specific ascending or descending order

The following example shows a customURL callback. By setting this user-created callback function on the Collection's customURL property, the Collection will call out to this function when it needs information to make a REST call.

function myCustomFunction(operation, collection, options) {
     // Use the default if operation is create
     if (operation === "create") {
         return null;
    }
     if (operation === "delete") {
        // Just set a URL if it's delete
        return "http://destroy/model='+options['recordID'];
     }
     var retObj = {};
     if (operation === "read") {
         retObj['url'] = "http://fetch";
         if (options['sort']) {
           retObj['url'] += "/order="+options['sort'] + ";" + options['sortDir'];
         }
         retObj['headers'] = {my-custom-header:"header-value"};
         retObj['mimeType'] = "text/plain";
         return retObj;
     }
     // Update or patch
     retObj['url'] = "http://update/model="+options['recordID'];
     retObj['type'] = "POST";
     retObj['beforeSend'] = myBeforeSendCallback;
     return retObj;
}

Replacing oj.sync or oj.ajax Functions

You can replace oj.sync() or oj.ajax() when you need to change the entire client-server transport mechanism. For example, this option is best if you want to use WebSockets instead of AJAX calls to the server.

The oj.sync method is the master server access method for all models and collections and accepts the following parameters:

oj.sync = function(method, model, options)

Valid values for the method parameter are the CRUD operations: create, read, update, patch, and delete. The model parameter accepts either the oj.Model being created, read, updated, patched, or deleted, or the oj.Collection being read. Options are passed down from the higher-level common model API call and vary with the type of operation.

The replacement oj.sync() method is completely responsible for implementing all of these operations using whatever transport mechanism is being used, whether it be the application's own AJAX routines, WebSockets, a JavaScript server, or something else. The method must return a Promise object similar to the AJAX XMLHttpRequest (XHR) in order to maintain compatibility with potential virtual API calls being made by the oj.Model and oj.Collection object.

Note:

Replacing oj.sync() replaces the transport mechanism for the JET common model used by all calls within the application. This is a very advanced use of the Oracle JET common model.

The oj.ajax() method is the master AJAX entry point for all oj.Model and oj.Collection server interactions, when they are using the default sync implementations. oj.ajax() passes its parameters and return value through to the jQuery.ajax() method by default. For additional information about the jQuery.ajax() method's expected parameters and return value, see http://api.jquery.com/jquery.ajax.

For additional information about the oj.sync() or oj.ajax() methods, see the Oracle JET oj.sync() and oj.ajax() API documentation.