Loose coupling of systems is key to future development! Why? Because it will allow us to change the "components" as we go along instead of creating monster big systems that are tied together using all sorts of different technologies. Webservices have been a way to obtain this over the last decade. More recently a special variant has become very popular, namely the JSON based REST service. Imagine you could extend your data out to the world outside your Domino environment? - in an easy way....! And imagine those data could easily be incorporated into other systems via standardized interfaces... Could that extend the value of your current systems further? Could this be a way to use new technologies to modernize your users' experience of working with your systems? Come and take away knowledge about how to open your Domino/XWork based systems up to the world outside using JSON based REST services. They are going to be key to future development in Domino/XWork - whether you want to use data in browser solutions (e.g. based on angular.js or ExtJS) or native mobile apps (built in whatever technology is best).

1. REST services
and
IBM Domino/XWork
by John Dalsgaard

2. 7th Sutol Conference, November 2015
Thanks to our sponsors!

3. 7th Sutol Conference, November 2015
3
Agenda
● About me
● Webservices
● REST & JSON
● Domino/XWork – out of the box...
● Domino Access Service (DAS)
● Extension Library controls
● Build your own
● Demos
● Round up

4. 7th Sutol Conference, November 2015
4
About me
● Worked with Notes since 1995
version 4.5
● Java since Notes 5.0.7 (2000)
● Large web-apps. (40.000+ users)
● Object Oriented approach since 1999 (yes, in
LotusScript...)
● XPages & mobile apps (Appcelerator Titanium)....
● Certified Principal/advanced administrator and
developer – all versions 4.6 → 9.0
● Developer, project manager, IT manager – own
company (Dalsgaard Data A/S) since 1998.
● IBM Champion for 2015

5. 7th Sutol Conference, November 2015
5
About me

6. 7th Sutol Conference, November 2015
6
Webservices
● What is a webservice?
● Program to program communication
● Implemementation independent
● ”Contract” about interface
● Traditionally SOAP & XML...
● Very ”verbose” (=not ”light”)
● Needs pre-/post processing to ”extract” data
→ Meet the ”new kid on the block”:

7. 7th Sutol Conference, November 2015
7
REST services using JSON
● REST = REpresentational State Transfer
● JSON = JavaScript Object Notation
● Why?? → Loose coupling...
● Angular, Ext.js, etc.
● Mobile apps/web apps
● Let's take a quick look at these terms:

8. 7th Sutol Conference, November 2015
8
REST
● Wikipedia:
Representational state transfer (REST) is an abstraction of the
architecture of the World Wide Web; more precisely, REST is an
architectural style consisting of a coordinated set of architectural
constraints applied to components, connectors, and data elements,
within a distributed hypermedia system. REST ignores the details of
component implementation and protocol syntax in order to focus on the
roles of components, the constraints upon their interaction with other
components, and their interpretation of significant data elements.....
WHAT?????

9. 7th Sutol Conference, November 2015
9
REST
● Client-server architecture
● Uniform interface separates client from server
● Stateless
● All info in request
● Cacheable communications protocol
● Almost always HTTP
● Uniform interface...
● HTML, URIs, XML, JSON, MIME, meta-data....
● Actually, WWW via HTTP can also be viewed as a REST-based
architecture – so nothing new here that you did not know... :-)

10. 7th Sutol Conference, November 2015
10
”RESTful” web-service
● Architectural style:
● URI structure (base URI)
● Internet media type. JSON – or: XML, Atom, …
● Standard HTTP methods:
● GET
● POST
● PUT
● DELETE
… also known as: CRUD (Create, Read, Update,
Delete) methods

11. 7th Sutol Conference, November 2015
11
”RESTful” web-service
● Designed for networked applications
● Using HTTP as a simple alternative to more
complex mechanisms to connect between
machines:
● WebServices (SOAP, WSDLs etc.)
● CORBA
● RPC

12. 7th Sutol Conference, November 2015
12
”RESTful” web-service
● Example – SOAP:
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:body pb="http://www.acme.com/phonebook">
<pb:GetUserDetails>
<pb:UserID>12345</pb:UserID>
</pb:GetUserDetails>
</soap:Body>
</soap:Envelope>
● … must be sent via a request (HTTP POST)
● Example – RESTful web-service:
http://www.acme.com/phonebook/UserDetails/12345
● … just a URL!! (HTTP GET) – simple....

13. 7th Sutol Conference, November 2015
13
JSON
● Wikipedia:
JSON (/ d e sən/ jay-sən), orˈ ʒ ɪ JavaScript Object Notation, is an
open standard format that uses human-readable text to transmit
data objects consisting of attribute–value pairs. It is used primarily
to transmit data between a server and web application, as an
alternative to XML.
Although originally derived from the JavaScript scripting
language, JSON is a language-independent data format. Code for
parsing and generating JSON data is readily available in a large
variety of programming languages.

14. 7th Sutol Conference, November 2015
14
JSON
● A syntax for storing & exchanging data
● An easier to use alternative to XML
● Is a lightweight data interchange format
● Is language independant
● Is ”self-describing” and easy to understand
JSON uses JavaScript syntax, but the JSON format is text only,
just like XML. Text can be read and used as a data format by any
programming language...

15. 7th Sutol Conference, November 2015
15
JSON vs. XML
● XML
<employees>
<employee>
<firstName>John</firstName> <lastName>Doe</lastName>
</employee>
<employee>
<firstName>Anna</firstName> <lastName>Smith</lastName>
</employee>
<employee>
<firstName>Peter</firstName> <lastName>Jones</lastName>
</employee>
</employees>
● JSON
{"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter", "lastName":"Jones"}
]}

16. 7th Sutol Conference, November 2015
16
JSON syntax
● Object: {}
{ 'text' : 'Hello world!',
'number' : 123,
'valid' : true }
● Array: []
{ 'numbers' : [ 1, 2, 3 ] }
{ 'objects' : [ {'a':1}, {'b':2}, {'c':3} ] }
● Value:
● string, number, object, array, boolean, null
● Please note: NO date/time type...!!! Grrrrr.....

17. 7th Sutol Conference, November 2015
17
JSON and JavaScript
● Sample data:
var text = ”{ 'name' : 'SUTOL', 'current' : 2015 }”;
● Create an object:
● var sutol2015 = JSON.parse(text);
● Create text representation of an object:
● var sutol2015Text = JSON.stringify(sutol2015);
● Refer to attributes:
● var name = sutol2015.name;
● Add another attribute:
● sutol2015['venue'] = 'London'

18. 7th Sutol Conference, November 2015
18
Domino/XWork - out of the box
● Webservices (SOAP, XML, etc...)
● Provider (server) – since 7.0
● Consumer (client) – since 8.0
● Written in LotusScript/Java
RESTful service using JSON →
● Domino Access Services (DAS)
● core service - since 9.0.1
● data service - since 8.5.3 UP1 (~DDS)
● calendar service - since 9.0.1

19. 7th Sutol Conference, November 2015
19
Domino Access Services
● Implemented as OSGi plugins/servlets
● Based on Apache Wink
● How to enable & configure
● Web access
● Enable Domino Access Service (DAS)
● Enable for database
● Enable for specific elements

20. 7th Sutol Conference, November 2015
20
Enable web access
● HTTP Server must be started.
● Check console: show tasks
HTTP Server Listen for connect requests on TCP Port:80
● Use internet sites – just do it!
● Activate in server document
● Create Internet site document for domain
● After changes: restart task http
● Check:
● Open the server on the port you saw on the console
● http://server.dom.dk:80/ (leave out port if 80)

21. 7th Sutol Conference, November 2015
21
Check DAS
Open: server.dom.dk/api
● lists services and
their state

22. 7th Sutol Conference, November 2015
22
Enable data service
● On Internet site document (configuration tab):
● Need to refresh http to take effect
● tell http refresh

23. 7th Sutol Conference, November 2015
23
DAS: List all ”services” (db's)
● Open: server.dom.dk/api/data

24. 7th Sutol Conference, November 2015
24
DAS: Open a specific database
● Try: server.dom.dk/reports.nsf/api/data/collections
→ We need to enable DAS for the database

25. 7th Sutol Conference, November 2015
25
DAS: Enable for database
● On the advanced properties of the database:
● Select level in ”Allow Domino Data Service”:
● Important decision:
● Views only or views and documents

26. 7th Sutol Conference, November 2015
26
DAS: Open database again
● Try: server.dom.dk/demo/json.nsf/api/data/collections

27. 7th Sutol Conference, November 2015
27
DAS: Enable for view
● We need to enable DAS for the view first
● Open the view in Domino Designer
● On the view properties – advanced tab
● Enable: ”Allow Domino Data Service operations”:
● Save the view, open it using the url returned

28. 7th Sutol Conference, November 2015
28
DAS: Open a view
● Try: server.dom.dk/.../collections/unid/A892133953...
● Heureka!! - we see a list of all documents!
● Also try: server.dom.dk/.../collections/name/persons

29. 7th Sutol Conference, November 2015
29
DAS: Open a document
● Try: server.dom.dk/.../documents/unid/33735D0BC...
● Requires ”Views and documents” to be set in DB props.

30. 7th Sutol Conference, November 2015
30
DAS: Writing back...
● Remember content type MUST be:
● application/json
● Set ”Content-type” in header of request
● If you get ”405 Method not allowed”
● Enable method in internet site
● By default these are NOT enabled:
● PUT
● PATCH
● DELETE
● Or override header in your request
● ”X-HTTP-Method-Override” : ”POST”

31. 7th Sutol Conference, November 2015
31
DAS: Save existing document
● Use ”PATCH” to change specific fields
● url: …/documents/unid/33735D0BCE799....
● updates only the fields in the request
● Use ”PUT” to change ALL fields
● url: …/documents/unid/33735D0BCE799....
● All fields are replaced with the fields from
request – fields not specified are blanked....

32. 7th Sutol Conference, November 2015
32
DAS: Create / delete document
● Use ”POST” to create a document with
specified fields
● url: …/documents?form=Person
● You MUST add form to url
● Use ”DELETE” to remove the document
entirely
● url: …/documents/unid/33735D0BCE799....

33. 7th Sutol Conference, November 2015
33
DAS: Data service - more...
● See the design of a view:
● //.../collections/name/persons/design
● Compute values on update of document
● //.../documents/unid/33735D0BC...?computewithform=true
● Use ”normal” url actions to control view collection,
e.g.
● //.../collections/name/persons?start=1&count=2

34. 7th Sutol Conference, November 2015
34
Live
D
EM
O

35. 7th Sutol Conference, November 2015
35
Demo...
● Server:
● Local VM with Domino 9.0.1FP2 on CentOS 6.7
● Extension Library (from IBM)
● OpenNTF Domino API installed
● OpenNTF Essentials installed
● A demo database (download from Bitbucket.org)
● Showing an MVC pattern I use
● Added a number of JSON demos
● Is available for download
● Tool for testing:
● Google Chrome Postman

36. 7th Sutol Conference, November 2015
36
DAS: Calendar service
● There is a ”catch” to enabling this service...
● In the internet site document you have to type
”Calendar” as an option.... - it is not predefined

37. 7th Sutol Conference, November 2015
37
DAS: Calendar service
● Built on the new calendar backend classes in
Domino/XWork 9.0.1
● Current user's calendars, email address, and
services
server.dom.dk/api/calendar
● Events from specific calendar
server.dom.dk/demo/cal.nsf/api/calendar/events
● Events from specific calendar (iCal format)
server.dom.dk/.../events?format=iCalendar
● Only shows events that have NOT started yet

38. 7th Sutol Conference, November 2015
38
DAS: Calendar service
● You can also CREATE new events!!!
● Using POST and specifiying all fields under an
”events” object
● Handles the various types: Meeting, appointment,
etc.
● Will send invites to participants of meetings
● Handles notifications
● Actions for complete workflow: Accept, decline,
delegate, etc.
● … and more!

39. 7th Sutol Conference, November 2015
39
DAS: Calendar service
● You can also UPDATE existing events!!!
● Using PUT and specifiying ALL fields under an
”events” object – as it is returned by creating or
getting the event
● Use ”.../events/<exact id as from request>
● including ”....-Lotus_Auto_Generated” !!!
● You should keep all fields – including system fields
● If you don't → Defaults are applied...
● E.g. specifying only start time → end time set to same..!!!
● Failure to follow these guidelines will result in an error
400 ”Bad request”

40. 7th Sutol Conference, November 2015
40
Live
D
EM
O

41. 7th Sutol Conference, November 2015
41
Extension Library
● Comes with the Domino 9.0.x server (and Domino
Designer)
● Just needs to be enabled in XSP properties
● Does NOT require DAS to be enabled
● Provides easy to use controls:
● REST Service (data)
● Remote Service (JSON-RPC)
● Allow you to run serverside code as a REST service...
● Also provide support for:
● NSF and OSGi servlets... - advanced stuff!!

42. 7th Sutol Conference, November 2015
42
Extension Library
● Why would you use it...????
● → Allows further customizations
● Include/exclude certain data columns
● Include/exclude system columns (@....)
● Calculate contents of own columns
● Run code before/after CRUD operations
● Sort and search
● Create ”handles” (variable) to use in XPage as
datasources

43. 7th Sutol Conference, November 2015
43
Ext. Lib. REST Service
● Create a new XPage
● Drag a ”REST Service” component
to it:
● Fill in ”the blanks”
● pathInfo → identifies
the service
● Select service
● Fill in the info
needed for that
type of service

44. 7th Sutol Conference, November 2015
44
Ext. Lib. REST Service
● To call your service you open the XPage with the
REST Service control(s) and add the pathInfo, e.g.:
server.dom.dk/db.nsf/yourpage.xsp/persons
● ...assuming you set pathInfo to ”persons” for one of
the REST Services on the ”yourpage” XPage

45. 7th Sutol Conference, November 2015
45
Ext. Lib. NSF servlet
● You can register a servlet to e.g. give you a
JSON representation of a view
● Extends DefaultServletFactory
● add a factory that maps to a service (e.g. view
name)
● Register in Code/Java/META-INF/services
● file: com.ibm.xsp.adapter.servletFactory
→ Full name of servlet class
● Refer to using url, e.g.:
server.dom.dk/db.nsf/xsp/services/Persons
● Does NOT require DAS to be enabled

46. 7th Sutol Conference, November 2015
46
To come: Extend DAS through
OpenNTF Domino API (ODA)
● This is work in progress by Nathan T. Freeman
● Learn more by attending webinar on 17
November (next week!!) by TLCC:
http://www.tlcc.com/xpages-webinar
… and if you don't use ODA already then you
should start NOW!

47. 7th Sutol Conference, November 2015
47
Live
D
EM
O

48. 7th Sutol Conference, November 2015
48
Build your own...
● Why??
● … using your own MVC – Java objects
● Full control
● Does NOT require DAS to be enabled
● Handy ”ingredients”
● Java
● XPages
● Use an ”XAgent” (or an NSF/OSGi servlet)
● Select a JSON ”package”
● Built-in with XPages
● Or others like GSON – (wrap as plugin!!)

49. 7th Sutol Conference, November 2015
49
Build your own...
● Use cases:
● Generate JSON directly from your Java class
● Consume your JSON POSTs directly by parsing
them to the corresponding Java class
→ Ready to use in your logic
● Control e.g. date formating generally for all Date
fields
● Eg. use ISO datetime format

50. 7th Sutol Conference, November 2015
50
Build your own...
● LotusScript....
● You didn't expect me to say this!
● An option if you have existing systems with
business logic written in LotusScript
● Simple:
● print – correct content-type
● print …. your JSON (as text)
● … but I would not advice to build new this way →
you would like to use a library/package to build your
JSON for you!
● Does NOT require DAS to be enabled

51. 7th Sutol Conference, November 2015
51
Live
D
EM
O

52. 7th Sutol Conference, November 2015
52
Round Up
● What are REST and JSON
● GET, POST, PUT, DELETE – ~CRUD
● Domino Access Services – out of the box
● Data
● Calendar
● Extension Library
● REST Service
● (Remote Service)
● Build own solution
● Java & JSON ”package” - …. & LotusScript ;-)

53. 7th Sutol Conference, November 2015
53
Questions??
● Did you learn something?
● Could you use it?
?

54. 7th Sutol Conference, November 2015
54
Contact info
Please feel free to contact me:
John Dalsgaard
Dalsgaard Data A/S
Solbjergvej 42
Solbjerg
DK-4270 Høng
Phone: +45 4914-1271
Email: john@dalsgaard-data.dk
www.dalsgaard-data.dk
Blog: www.dalsgaard-data.eu
Twitter: @john_dalsgaard, @DalsgaardDataAS
Skype: john_dalsgaard

55. 7th Sutol Conference, November 2015
55
Sources & links
● Wikipedia: Representational state transfer
● Learn REST: A Tutorial
● VIEW Tips: Brad Balassaitis on JSON-RPC
● IBM Domino Access Services 9.0.1
● Wikipedia: JSON / JavaScript Object Notation
● Introducing JSON
● JSON Tutorial
● REST services in Domino - Domino Access Services (PDF)
● Extension Library REST Services (PDF)
● Extension Library on OpenNTF (includes demo db)
● JSON test client: Chrome Postman
● Wrap an existing jar into a plugin
● Demo-DB on Bitbucket.org

56. 7th Sutol Conference, November 2015
56
Sources & links
● For the advanced – check these frameworks....
● Apache Wink (what DAS etc. is build on)
● … and Wink with OpenNTF Extension Library
● Jersey
● Specifikation: Java API for RESTful Services (JAX-RS)