restful services on ibm domino/xwork (sutol 11 nov. 2015 in prague)

REST services and

IBM Domino/XWorkby John Dalsgaard

7th Sutol Conference, November 2015

Thanks to our sponsors!


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

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

About me


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

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

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?????

https://en.wikipedia.org/wiki/Representational_state_transfer


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

”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

”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

”RESTful” web-service● Example – SOAP:

<?xml version="1.0"?><soap:Envelopexmlns: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

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.

https://en.wikipedia.org/wiki/JSON


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

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

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

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

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

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

Enable web access● HTTP Server must be started.

● Check console: show tasksHTTP 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)

http://server.dom.dk:80/


21

Check DAS

Open: server.dom.dk/api● lists services and

their state


22

Enable data service● On Internet site document (configuration tab):

● Need to refresh http to take effect● tell http refresh


23

DAS: List all ”services” (db's)

● Open: server.dom.dk/api/data


24

DAS: Open a specific database● Try: server.dom.dk/reports.nsf/api/data/collections

→ We need to enable DAS for the database


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

DAS: Open database again

● Try: server.dom.dk/demo/json.nsf/api/data/collections


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

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

DAS: Open a document● Try: server.dom.dk/.../documents/unid/33735D0BC...

● Requires ”Views and documents” to be set in DB props.


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

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

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

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

Live D

EMO


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

https://bitbucket.org/john_dalsgaard/json/overview


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

DAS: Calendar service● Built on the new calendar backend classes in

Domino/XWork 9.0.1● Current user's calendars, email address, and

servicesserver.dom.dk/api/calendar

● Events from specific calendarserver.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


● 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


● 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

Live D

EMO


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

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

Ext. Lib. REST Service● Create a new XPage● Drag a ”REST Service” component

to it:● Fill in ”the blanks”

● pathInfo → identifiesthe service

● Select service● Fill in the info

needed for thattype of service


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

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

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

Live D

EMO


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!!)

http://www.dalsgaard-data.eu/blog/wrap-an-existing-jar-file-into-a-plug-in/


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

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

Live D

EMO


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

Questions??● Did you learn something?● Could you use it?

?


54

Contact infoPlease feel free to contact me:

John DalsgaardDalsgaard Data A/SSolbjergvej 42SolbjergDK-4270 Høng

Phone: +45 4914-1271Email: [email protected]: www.dalsgaard-data.euTwitter: @john_dalsgaard, @DalsgaardDataASSkype: john_dalsgaard

mailto:[email protected]

http://www.dalsgaard-data.dk/

http://www.dalsgaard-data.eu/


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

http://en.wikipedia.org/wiki/Representational_state_transfer

http://rest.elkstein.org/

http://www.socialbizug.org/blogs/0c23ff4a-b496-4b0e-9c8b-d0db0488bfed/entry/quick_tip_from_brad_balassaitis_improve_xpages_application_performance_with_json_rpc?lang=da

http://www-10.lotus.com/ldd/ddwiki.nsf/xpAPIViewer.xsp?lookupName=IBM+Domino+Access+Services+9.0.1#action=openDocument&content=catcontent&ct=api

http://en.wikipedia.org/wiki/JSON

http://www.json.org/

http://www.w3schools.com/json/

https://www.ibm.com/developerworks/community/files/form/anonymous/api/library/82e137de-50a2-4dc0-b648-4644afb7225e/document/af8634fb-6a43-47f6-ba46-47ae592a3d87/media/1.%20Domino%20Access%20Service.pdf&ei=zDNnVL9Cjc9ox8uByAc&usg=AFQjCNGQFBnw8PHH3iROM12wseKgzmQEUg&sig2=RpfQlhjdLx3DXjpWfYVyiw

http://www.openntf.org/Projects/pmt.nsf/36B7CD129ED7357A86257AC6005523E7/$file/Extension%20Library%20REST%20Services.pdf

http://extlib.openntf.org/main.nsf/project.xsp?r=project/XPages%20Extension%20Library/releases/FC420BE9BF48AE3C86257D4D0033007F

https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en

http://www.dalsgaard-data.eu/blog/wrap-an-existing-jar-file-into-a-plug-in/

https://bitbucket.org/john_dalsgaard/json/overview


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)

https://wink.apache.org/

http://www.openntf.org/main.nsf/blog.xsp?permaLink=NHEF-8R2AYQ

https://jersey.java.net/

https://jax-rs-spec.java.net/

restful services on ibm domino/xwork (sutol 11 nov. 2015 in prague)

Software