Sheetster REST API Security and Customization

Sheetster Users Groups and Permissions

Sheetster provides granular, role-based security for all documents and system resource. For details on the security implementation, please review the Security Guide.

Sheetster REST API Authentication

Sheetster Authentication need only be done once per session.
Once you have an authenticated session, you can just send the 'sessionid' header to maintain your session state on the server. Browsers do this automatically, from Java code, you can append this information to the request like so:

// get a unique id for this HttpSession
String seshid = session.getId();

// Open a connection to the URL
URLConnection pageConnection;
pageConnection = pageURL.openConnection();
if(sessionid!=null)
pageConnection.addRequestProperty("Cookie","sessionid="+seshid);

For stateless, or rare connections where you will not be maintaining session state, you can retreive an encrypted auth token that you can use instead of the 'username=xxx@acme.com&password=secret' authentication request.
We are still working on this particular feature, so for now please use the username/password params.
This token is somewhat more secure but its caller will be granted the same access rights as the logged-in user that it is based on. For this reason it is recommended to use public documents or append-only security rights in situations where secure access to the token might be compromised.

Java REST API Usage
Attached is a complete REST api unit test, all the stuff you want to do is in there from a Java perspective...

Client-Side REST API Usage

You can use JavaScript in the client to call these URLs dynamically from Ajax requests.
e360/Sheetster uses the prototype.js library for all AJAX and web2.0 functionality.

If you include the /common/module_header.jsp in your jsp files, you will have access to convenience methods like:

// wrap Prototype AJAX binding to a div container to standardize handling
var updatewithresponse = $('some_div');
// bind the REST call results to an HTML div
ajaxBind(updatewithresponse, '/workbook/id/1234/json/cellrange/get/Sheet!A1:VU1');

Creating a REST API Plugin
Depending on the complexity of your application, you may want to access the full power of the server from Java. In this case, the most solid architectural option is to create your own REST plugin and drop it in the WEB-INF/plugins directory. This gives you granular control over security and allows you to use the full power of Java to automate tasks and build your application.

The basic idea is that once you have built a plugin and put the compiled classfile in the plugins directory, you can then access your plugin methods in the same URL namespace as the e360 REST api. Which means you have all of the builtin security and spreadsheet messaging and api features at your command.

So if you had a plugin called:

PluginCustom.java:

public Object mymethod(Map params){
returns "hello world";
}

To call your custom plugin you would use the same AJAX code as above, with your plugin URL:

// bind the REST call results to an HTML div
ajaxBind(updatewithresponse, '/workbook/id/1234/json/custom/mymethod/Sheet!A1');

To call your custom plugin you would use the same AJAX code as above, with your plugin URL:

// bind the REST call results to an HTML div
ajaxBind(updatewithresponse, '/workbook/id/1234/json/custom/mymethod/Sheet!A1');

Handling REST Exceptions

When a REST api call does not succeed, you should receive an error message as output, typically in the format of the request when possible.

For example, if you request a resource as XML, and there is a failure, you would receive an error message as an XML object like so:

Something Bad

Depending on the nature of the error, you may need to troubleshoot further. Please refer to the Sheetster troubleshooting guide for more information.

Logging/Intercepting REST Calls

Occasionally you may wish to log and/or otherwise trigger events based upon the actions of users.

To intercept ALL calls to the REST api, you can create and install your own Java Servlet that extends the built-in Sheetster REST Servlet:

com.extentech.ExtenXLS.ESS.WorkBookServlet.java

The 2 methods you will need to override are:

public void doGet(HttpServletRequest request, HttpServletResponse response)
public void doPost(HttpServletRequest request, HttpServletResponse response)

Here is an example of the code that you can use to extend the functionality of these 2 builtin methods:

public void doGet(HttpServletRequest request, HttpServletResponse response) 
throws ServletException, IOException { 
this.runService(request, response); 
String lst = Logger.getLogDate() + ((ServeConnection)request).getRawRequest() + ":" + 
((ServeConnection)request).getUserPrincipal().toString(); 
myLoggerMethod(lst); 
}