HTML5, CSS3, jQuery, JSON, Responsive Design...

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"
});


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/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");
});


Here's a sample form to test the POST:

http://184.73.169.93/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

1Alan Hurt  04/09/2013 7:26:19 AM  Domino Data Services in Domino 9 - first fumblings!

If you can enable PATCH, do it...it is extremely useful for cases like in-line editing, etc.

2Oliver Busse  04/09/2013 6:06:14 PM  Domino Data Services in Domino 9 - first fumblings!

Awesome stuff - I also never heard of it before, so thanks for sharing it with us :-)

3Mark Roden  04/09/2013 6:50:21 PM  Domino Data Services in Domino 9 - first fumblings!

What Alan said !!!

Patch is fantastic - one field update at any time from anywhere allows you to update the database configs and all that mess without leaving the page!!

Love it!

Thanks for sharing :)

4Giulio Campobassi  04/09/2013 8:56:51 PM  Domino Data Services in Domino 9 - first fumblings!

This is pretty interesting. I was wondering about authentication, here { Link }

Is this header and using LTPAToken the only means of authentication ? Or is there any other secure method beyond using SSL /VPN ?

5Michael Brown  04/09/2013 10:47:17 PM  Domino Data Services in Domino 9 - first fumblings!

@Giulio,

I'm not passing any login credentials in my sample code.

Full Domino authentication seems to be implemented. E.g, my POST example code didn't work at first unless I was logged in. Simple reason: Anonymous was set to Reader. I set Anonymous to Author + Create to get it to work.

6Mark Swanson  04/12/2013 8:18:58 PM  Domino Data Services in Domino 9 - first fumblings!

Mike .. You should also check out the use of the collection api in Domino Data Services as I'm currently using this to return medium to large data sets (20,000 or more) documents in JSON format which can be accessed by HTTP in a URI and the data can then be integrated with other SOA compliant systems IE. Java Web Apps, Oracle, JDE etc.

The data can be accessed concurrently by multiple systems, and it takes approx 16 seconds to return 20,000 docs in JSON (not ideal, as it would be nice to get the dataset in milliseconds, but still quicker than using a Domino agent to build the dataset).

DDS is a far more secure and cleaner approach than integrating data with CSV files, as a lot of organisations still do. This feature allows Domino to fit into a more SOA compliant architecture where it should have been years ago.

Firstly, it is easier to deploy on both Domino 9 and Domino 8.5.3, although it is a bit more of a fiddle on 8.5.3 as you need to install the IBM Domino Upgrade pack 1 first. No need to do this in 9 as the upgrade pack has been incorporated.

Secondly, you can apply SSL encryption.

I would recommend reading the chapter on Domino's REST services in the IBM xPages Extension Library documentation if you really want to do know more about Domino Data Services.

7Martin Rolph  07/01/2013 6:50:44 AM  Domino Data Services in Domino 9 - first fumblings!

Great post. I've only just started looking at Domino Data Services too. Not much on the web about them. It's as if they're a secret or something!

8Sean Haggerty  10/08/2013 10:17:03 AM  Domino Data Services in Domino 9 - first fumblings!

I heard mention of an .ini setting that needs to be set to turn on "Allow Domino Data Services" option to be available under the Propeller Hat (Advanced) tab of the Database Properties at the bottom.

{ Link }

Any insight on what the setting is, form some reason Hideloff, awesome as he is, didn't simply state what the ini setting is but only mentioned it was well documented (~erg).

This is a great post Brownie! Thx

9Michael Brown  10/08/2013 6:22:06 PM  Domino Data Services in Domino 9 - first fumblings!

@Sean,

Yes, I did mention that .ini file setting in my own post. But it's only required for Notes 8.5.3. I did not need to set it for Notes 9, so I don't know what it's called either.

10Thorben Hellweg  11/07/2013 3:47:17 AM  Domino Data Services in Domino 9 - first fumblings!

Hi Michael,

I'm quite new to DDS, so maybe I've missunderstood something, but is there no need to authenticate at the server?

11Michael Brown  11/07/2013 5:49:07 AM  Domino Data Services in Domino 9 - first fumblings!

@Thorben,

I'm quite new to it myself!

But, if I understand your question correctly, no, DDS is not a back door; you don't get access to Domino data via DDS unless you are logged in.

12Patrick Kwinten  04/16/2014 7:58:01 AM  more examples?

hi, I am looking into Domino Access Services / Domino REST Services or whatever it is called nowadays. Your samples are a great start!

Can you provide more common use case examples how to read/write via the service??

13David   06/17/2014 2:49:01 AM  Domino Data Services in Domino 9 - first fumblings!

I did simulate test of your sample and not able to update the data to the lotus notes database . I found the error from the log

Error from server- can you do search of this error

06/17/2014 03:38:57 PM HTTP JVM: ship.com/domino/html/fakenames.nsf/api/data/documents

06/17/2014 03:38:57 PM HTTP JVM: 31298020 [Thread-10] ERROR org.apache.wink.server.internal.RequestProcessor - An unhandled exception occurred which will be propagated to the container.

would appreciate if you can advise what is this error and resolution for this error

Many thanks in advance

14Dost Shah  05/10/2016 4:11:26 AM  Domino Data Services in Domino 9 - first fumblings!

I am using Domino server 9.0.1 in additional server mode, that connects to a main server for syncing the data which has a Domino server 8.5.3 . I am not able to get the option under Web Engine tab to enable DAS.

If I install this 9.0.1 serevr in standalone mode the option is there?

What can be the reason?

About