Domino Data Services in Domino 9 - first fumblings!
Michael Brown April 9 2013 06:12:34 AM
I've been playing with Domino Data Services in Notes/Domino 9.I've never looked at this in Domino before. And every bit of info that I found on the subject, when I did start looking, seemed to tell me that I had to write xPages, dojo.js controls and install the xPages Library from openntf.org. Maybe that was true in the past, but with Notes/Domino 9 you don't need any of that to get started. Everything I've played with so far involved no more than a bit of JavaScript and jQuery. Here's the official documentation that I followed:
http://www-10.lotus.com/ldd/ddwiki.nsf/xpDocViewer.xsp?lookupName=Domino+Data+Service
You can see that there's all the standard CRUD (Create, Read, Update, Delete) commands that you need, i.e. POST, GET, PUT and DELETE. Plus there's another one called PATCH, although I'm not sure why that's required when you already have PUT. Hell, there's even computwithform switches to let you run form formulae on save! Everything you need to start building RESTful services, in fact.
There's some housekeeping before you can get started. You have to enable Domino Data Services (which I'll abbreviate to DDS from this point on) at the server level, the database level and possibly at the view level too.
Enabling At Server Level
Open your Server document (or Web Site document if you're using those) and look for the Domino Access Services section. It's under the Internet Protocols -> Domino Web Engine tabs on the Server document, or under the Configuration tab on the Web Site document. There's only one field: Enabled services. Set it to "data" and save your document.
I restarted the server at the point, although I'm not sure it was necessary. A "tell http restart" might have been enough.
Enabling at Database Level
Open your Database Properties using the Notes client. Under the far-right, "propeller-head" tab, you should see a new field: Allow Domino Data Service. In Notes 8.5.3, I believe you needed a notes.ini variable set to see this field, but in Notes 9 it's just there. Set it to "Views and Documents".
That's all the housekeeping you need do for some simple testing. Now let's get into some code.
A Sample GET
This example makes a jQuery Ajax call to the sample NAB/Directory database, called fakenames.nsf. It uses DDS to query /api/data/documents to return JSON data about those documents. NB: /api/data/documents is one of the fixed paths used by DDS; there is no actual view/folder of that name in the database design, at least not a normal one that you can see in the Designer.
$.ajax({
url: "/tools/fakenames.nsf/api/data/documents",
type: "GET"
});
url: "/tools/fakenames.nsf/api/data/documents",
type: "GET"
});
Here's a sample web form that uses the code above to retrieve the documents JSON data and display it on the screen when you've clicked the button.:
http://184.73.169.93:8080/mike/testjson.nsf/ftforms/testget
A Sample POST
The example code makes a POST to the same test NAB/Directory database. It uses a jQuery Ajax call to pass (stringified) JSON to create a new Person document with defined FullName field.
For RESTful services, however, it's little use to be able to POST/create such a document without getting a handle on a unique ID by which you can then access it again. In Notes, of course, what you want to get is the new Document Unique ID (or UNID) And thankfully, the DDS POST call does pass the UNID back to your callback function as the Location parameter, but you do have to dig around a little find it. The Location parameter is actually in the Response Header of the callback though, and you can access this via jQuery's .getResponseHeader() method. You can see this in the .done() function call below. (NB: .done() is replacement for the now deprecated "success" function in jQuery's $.ajax() function.)
var newPersonObj = {Form: "Person", FullName: "Benji Marshall"};
$.ajax({
url: '/tools/fakenames.nsf/api/data/documents',
type: 'POST',
data: JSON.stringify(newPersonObj),
dataType: 'xml',
accepts: {
xml: 'text/xml',
text: 'text/plain'
},
contentType: "application/json"
}).done(function(data, textStatus, jqXHR) {
var newPersonLocation = jqXHR.getResponseHeader("Location");
});
$.ajax({
url: '/tools/fakenames.nsf/api/data/documents',
type: 'POST',
data: JSON.stringify(newPersonObj),
dataType: 'xml',
accepts: {
xml: 'text/xml',
text: 'text/plain'
},
contentType: "application/json"
}).done(function(data, textStatus, jqXHR) {
var newPersonLocation = jqXHR.getResponseHeader("Location");
});
Here's a sample form to test the POST:
http://184.73.169.93:8080/mike/testjson.nsf/ftforms/testpost
Enter a name and click the button. DDS will create a new document, grab the Location parameter of the new doc and display it on the screen as a clickable URL. Clicking on that URL actually returns JSON data about your new document. That's because it points to your new UNID at /ap/documents/unid, which is another special path used by DDS. Once again, there is no actual view/folder of that name in the database design that you can see in the Designer client.
- Comments [6]
