Ringing the Changes in the Force.com JavaScript REST Toolkit

The Force.com JavaScript REST Toolkit ('ForceTK' for short) is a minimal JavaScript wrapper for the Force.com REST API. This blog entry looks at recent changes that bring it up to date with the evolution of the Salesforce1 Platform.

Although there are now many, many ways to interact with Force.com from JavaScript, the Force.com JavaScript REST Toolkit (or ‘ForceTK’), first released in March 2011, was one of the pioneers, and remains one of the most popular. ForceTK provides a fairly minimal JavaScript wrapper for the Force.com REST API, with methods to create, retrieve, update and delete records, freeing the developer from the chore of constructing resource URLs and making HTTP calls.

The Salesforce1 Platform (comprising Force.com, its REST API and much more) is anything but static, however, and ForceTK has just undergone a minor refit to bring it up to date. Let’s take a look at three changes in the current version.

One of the main benefits of ForceTK is that it provides the same interface for accessing the Force.com REST API from JavaScript running in Visualforce, on external servers, and in hybrid mobile apps. Part of this abstraction is routing calls via a proxy where the browser’s Same Origin Policy prohibits direct calls to the Force.com REST API endpoint. From Spring ’13 on, the endpoint (/services/data) is exposed on the Visualforce servers, so the proxy is not required. The library will automatically call the REST API directly in this case. Note that Apex REST methods (/services/apexrest) still require the proxy.

A downside of using the REST API is that API calls are a limited resource. RemoteTK was written to allow JavaScript on Visualforce pages to avoid consuming API calls by using JavaScript Remoting, but came with a trade off – since calls were routed via an Apex controller, they operated with system-level privileges. Visualforce Remote Objects, released in Winter ’15, provide a much better mechanism, since they correctly respect user-level sharing rules and field level security. RemoteTK has been removed from the toolkit, and developers should migrate their code to Visualforce Remote Objects.

One final addition is the ability to insert and update Blob data via multipart messages – a REST API feature currently available through a pilot program. It is possible to insert or update blob data using a non-multipart message (by passing base64-encoded data in a JSON or XML-encoded message), but if you do, you are limited to 50 MB of text data or 37.5 MB of base64–encoded data. Using multipart messages, you can upload files of any type with a size of up to 500 MB. The new createBlob and updateBlob functions allow creation of ContentVersion records and creation and update of Document records. Here’s a minimal example that shows how it works:

<apex:page>
    <script src="{!$Resource.forcetk_new}"></script>
    <p>
        Select a file to upload as a new Chatter File.
    </p>
    <input type="file" id="file" onchange="upload()"/>
    <p id="message"></p>
    <script>
        var client = new forcetk.Client();
        client.setSessionToken('{!$Api.Session_ID}');

        function upload() {
            var file = document.getElementById("file").files[0];
            client.createBlob('ContentVersion', {
                Origin: 'H', // 'H' for Chatter File, 'C' for Content Document
                PathOnClient: file.name
            }, file.name, 'VersionData', file, function(response){
                console.log(response);
                document.getElementById("message").innerHTML = 
                    "Chatter File created: <a href=\"/" + response.id + 
                    "\">Take a look!</a>";
            }, function(request, status, response){
                console.log(response);
                document.getElementById("message").innerHTML = 
                    "Error: " + status;
            });
        }
    </script>
</apex:page>

If you’re using ForceTK, grab the new version and let me know what you think in the comments.

Published
December 11, 2014
Topics:

Leave your comments...

Ringing the Changes in the Force.com JavaScript REST Toolkit