Engage 2019: Your Data in the Major Leagues: A Practical and Updated Guide to RESTful Domino v10

#engageug
Your Data in the Major Leagues:
A Prac6cal and Updated Guide
to RESTful Domino v10
Serdar Basegmez
Developi
serdar_basegmez vanakentom
Tom Van Aken
GroupWave

#engageug
Serdar Basegmez
• IBM Champion Alumni (2011 - 2018)
• Developi InformaCon Systems, London
• Notes/Domino/XPages Developer, half-blooded admin!
• Member Director at OpenNTF Board
• Blog: LotusNotus.com [English / Turkish]
• Blogger and Podcaster on ScienCﬁc SkepCcism / CriCcal Thinking
serdar_basegmez

#engageug
Tom Van Aken
• First Cme IBM Champion in 2019
• Groupwave, KonCch - Belgium
• Notes Domino / Xpage developer
• Blog: vanakentom.wordpress.com [Dutch]
vanakentom

#engageug
Agenda
• RESTful Architecture
• PracCcal ImplicaCons and Advantages of RESTful Services
• Ways to Provide REST Services for IBM Domino
• Consuming REST Services within IBM Domino
• Wrap-up

#engageug
RESTful Web Services
Source: https://en.wikipedia.org/wiki/Representational_state_transfer
Representa)onal state transfer (REST) is an architectural style used
for web development. Systems and sites designed using this style
aim for fast performance, reliability and the ability to scale (to grow
and easily support extra users). To achieve these goals, developers
work with reusable components that can be managed and updated
without aﬀec)ng the system as a whole while it is running.

#engageug Source: https://speakerdeck.com/jeffschenck/rest-easy-api-security-done-right
User Interface Business Logic Datastore
Front-end Back-end
ASP, PHP, CGI, Web Agents, JSP, etc.
← HTML, CSS, JavaScript
Forms →
Old School Web ApplicaCons

#engageug
Web ApplicaCons Evolving
Front-end Back-end
Async web apps, Ruby on Rails, Django, JSF, XPages, etc.
Forms, AJAX →

#engageug
Web ApplicaCons Evolving
Front-end Back-end
Modern Web frameworks, Angular.js, React.js, etc.
← REST →

#engageug
[Web] ApplicaCons Evolving
Mobile Applications
Back-end
← REST →
Front-end

#engageug
Mobile Applications Back-end
← REST →
Front-end Microservice Microservice Microservice

#engageug
Back-end
← REST →
Mobile Applications
Front-end
External Apps
Microservice Microservice Microservice Integration

#engageug
RESTful, Everywhere!
Solid Architecture
Well-deﬁned practices
Widespread use
Easily consumable
Scalable

#engageug
The ConversaCon Makes Sense!
Source: http://www.bizcoder.com/a-fresh-coat-of-rest-paint-on-a-soap-stack

#engageug
GET /twink/contacts/DLEY-ACLH6Y HTTP/1.1
Host: homer.developi.info
Cache-Control: no-cache
{
"zip": "13202",
"state": "NY",
"lastName": "Abbate",
"middle": "J",
"country": "US",
"emailAddress": "Jessica.J.Abbate@trashymail.com",
"number": "DLEY-ACLH6Y",
"city": "Syracuse",
"firstName": "Jessica"
}

#engageug
hPp://appserver.company.com/apps/contacts.nsf/
GiveMeTheContactWeNeedPleaseAgent?OpenAgent&id=1522
or…
hPp://appserver.company.com/api/contacts/1522

#engageug
Conventions on URLs
GET hPp://appserver.company.com/api/contacts
GET hPp://appserver.company.com/api/contacts/UK/London
POST hPp://appserver.company.com/api/contacts
Retrieve Contacts / Create a new Contact…

#engageug
Conventions on URLs
GET hPp://appserver.company.com/api/contacts/1522
PUT hPp://appserver.company.com/api/contacts/1522
DELETE hPp://appserver.company.com/api/contacts/1522
Retrieve/Update/Delete the Contact resource with id=1522…

#engageug
URI GET PUT POST DELETE
/contacts/ List Contacts Replace Contacts Create New Contact Delete Contacts
/contacts/id Retrieve a Contact Replace a Contact N/A (generally) Delete a Contact
Source: https://en.wikipedia.org/wiki/Representational_state_transfer

#engageug
Different Conventions
GET hPps://api.twiPer.com/1.1/statuses/show.json?id=1234567890
Retrieve the Tweet with id=1234567890…

#engageug
RESTful Services
for
IBM Domino Applica6ons

#engageug
Some InspiraCon
• New Front-ends and Enhanced UX
• JS Frameworks (e.g. Angular, React), Mobile Apps, etc.
• Grids, quick searches, becer type-aheads, etc.
• Richer experiences with chatbots, AI, etc.
• IntegraCon for third party sites/applicaCons
• Pull exchange rates, get weather info
• Get customers from CRM, create leads
• Upload to Box, Send to Slack…
• AutomaCng processes using APIs
• Push data to the AccounCng system…
• Access to ERP, check the inventory, iniCate a new PO
User Experience
Business Processes
Integration

#engageug
Providing RESTful Services
Domino Access Services
Extension Library REST Components
Hardcoded Solutions (Web Agents, XAgents, Servlets)
Advanced J2EE (JAX-RS)
SmartNSF
Node.js
#OpenNTF
#Domino10

#engageug
IBM Supported Fully Func6onal REST API
Access to Data / Calendar / Mail* / Freebusy* / Directory**
* Mail and Freebusy access is part of the core product since 9.0.1FP10 / ** Directory access is enabled with the ExtLib version of OpenNTF
Caching / Na6ve Security (ACL, Reader/Author ﬁelds, etc.)
Server-level / Database-level / Design-level control
Enable on Server Enable For Database Enable For Views

#engageug
• OpenAPI deﬁniCons (Swagger) are hosted on OpenNTF!
• hcps://github.com/OpenNTF/das-api-specs

#engageug
• Drawbacks:
• Weak control over the data!
• No checkpoints on CRUD, No coding involved…
• Weak control over the access.
• No place for business logic!
• Consumer has to implement all the business logic.
• Exposes internals
• You should trust consumers and the environment…

#engageug
REST Components (ExtLib)
• Provided and Supported by IBM
• Customizable component version of the DAS
• Computed/Filtered columns, Custom search, etc.
• Event model helps building business logic on top of REST model
• Custom REST Service
• Write your own SSJS or Java bean
• Write your CSJS rouCnes for async access
• Remote Service / JSON-RPC
• Dojo support for single page model

#engageug
• Setup REST component(s) on your page.
• Minimal coding, no administrator needed.
Add to your XPage Add a Service Conﬁgure Options

#engageug
• Drawbacks:
• Easy to slip into a spageh code!
• Java beans are your friends…
• Not opCmized for performance and scalability
• Diﬃcult to follow RESTful URL ConvenCon
https://someserver.domain.com/database.nsf/somepage.xsp/service/…

#engageug
Hardcoding (Web agents, XAgents, Servlets…)
• Old school way; sCll quite useful for some cases.
• Great if you have pre-exisCng code (e.g. Lotusscript libraries, etc.)
• Customizable, ﬂexible and simple way to create any service

#engageug
Hardcoding (Web agents, XAgents, Servlets…)
• Drawbacks:
• Hardcode everything…
• e.g. Header/parameter extracCon
• Very easy to slip into a spageh code!
• Error handling / proper tesCng needed
• Diﬃcult to follow RESTful URL ConvenCon
https://someserver.domain.com/database.nsf/xagent.xsp?…
https://someserver.domain.com/database.nsf/someagent?OpenAgent&…

#engageug
J2EE (JAX-RS) Methods
• JAX-RS: ‘Java-ish’ way to deﬁne RESTful services
• Create JAX-RS based REST services on top of OSGi plugins.
• Complete Java soluCon, extensible with custom providers
• OpCons
• Apache Wink 1.1.2 (DAS uses!)
• Jakarta EE
• RestEasy, Apache CXF, Jersey, etc.
• Code reusability outside IBM Domino world.

#engageug
On Apache Wink…
hcps://speakerdeck.com/sbasegmez/iconuk-2016-rest-assured...
On Jakarta EE… (by Jesse Gallagher)
hcps://github.com/OpenNTF/org.opennp.xsp.jakartaee

#engageug
• Drawbacks:
• Plugin only
• Diﬃcult if you are not familiar, Takes Cme to learn
• Overkill?
• Not suitable for small projects and simple needs
• Tool selecCon is criCcal.
• Apache Wink is old school
• IntegraCng alternaCves might be diﬃcult

#engageug
SmartNSF
• OpenNTF Plugin
• Beta-7 version.
• Developers:
• ChrisCan Güdemann
• MarCn Jinoch
• Deﬁne your REST Services from DDE!
• Uses Groovy
• Auto-generate OpenAPI deﬁniCons
Looking for Contributors!

#engageug
Node.js
• Just arrived: DQL + Domino AppDev Pack:
• Domino Query Language
• AppDev Pack: Proton Task / domino-db.js
• Countless opportuniCes in the most popular framework
• Diﬀerent possibiliCes for the architecture
• Wide range of opCons for tooling
https://insights.stackoverflow.com/survey/2019

#engageug
Node.js
IBM Domino Server
Proton
NSF
Node.js Layer
domino-db.js
GRPC
Application
………
ApplicationREST
New Add-on
Domino v10
Routers for
the RESTful service
Might be on the same box or not
MyRoutes.js

#engageug
Providing RESTful Services on Domino
Benefits Challenges Suggested When?
Domino Access Services 
(DAS)
Zero-setup
True RESTful
No Programming
No Business Logic
Exposes the Internals
Simple data exchange
ExtLib Components 
for REST
Less Backend Code
Minimal Setup
Partial/Full Customization
Error Handling
Spaghetti Code Risk
URL Convention
Simple needs for a limited
scope
Hardcoding 
(XAgents, Web agents…)
Tailor-made
Any Language is OK
Hardcoding Everything
Spaghetti Code Risk
URL Conventions
Very specific needs for a
limited scope
J2EE / JAX-RS
Tailor-made
OSGi Benefits
True RESTful
Learning Curve
Barrier to Entry
Environment Setup
Large scope implementation,
API Design
Node.js
Tailor Made
Node.js Benefits
True RESTful
Learning Curve
Still Improving
Environment Setup
Modernization Projects
SmartNSF Beta
Less Backend Code
True RESTful
Learning Curve
Limited Support
Simple needs for a limited
scope

#engageug
Consuming RESTful Services
…or Teaching your app to browse the Internet…
Language Preference?
Is it On-demand or Background?
Server-side or Client-side?
SDK? Authentication?

#engageug
Language Preference
• Server-side JavaScript
• Already uses Java. Eliminate the middleman…
• Java
• XPages Managed Beans, Java Agents, OSGi Plugins, etc.
• ConnecCng a remote
• URLConnecCon (Core Java)
• HcpComponents (Apache Commons)
• JSON Processing
• JsonJavaObject (IBM Commons)
• Jackson, Gson, etc.

#engageug
ConnecCng Java
• Pulling exchange rates via Java (Agent or Managed Beans)
public Double receiveEurUsdRate() throws Exception {
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpGet = new HttpGet("http://api.fixer.io/latest?base=USD");
CloseableHttpResponse response = httpclient.execute(httpGet);
try {
HttpEntity entity = response.getEntity();
// This is the worst practice ever!
// We don't check anything! Everything can go wrong...
JsonJavaObject ratesMap = (JsonJavaObject) JsonParser.fromJson(JsonJavaFactory.instanceEx,
EntityUtils.toString(entity));
JsonJavaObject rates = ratesMap.getAsObject("rates");
// We can write values into a NotesDocument
return rates.getAsDouble("EUR");
} finally {
response.close();
}
}
* Networking is a restricted operation for Agents! Agent Security should be conﬁgured.
Create an HTTP client
Get a Response
Convert to JSON

#engageug
ConnecCng SSJS
• Pulling exchange rates on an XPage acCon
<xp:button
id="button1" value="What is the exchange rate?">
<xp:eventHandler
event="onclick"
submit="true"
refreshMode="partial"
refreshId="computedField1">
<xp:this.action><![CDATA[#{javascript:
viewScope.EurUsdRate = test.ExchangeRate.receiveEurUsdRate()
}]]></xp:this.action>
</xp:eventHandler>
</xp:button>
* This code will run multiple times for each page cycle.
Always cache values!
Call Java (via Managed Bean)

#engageug
Reminder for Java
• Consuming any REST Service (When needed or on a schedule)
• Running from an Java Agent
• Import Apache HcpComponents/IBM Commons
• Conﬁgure Agent Security
• Running from an XPage / Java or SSJS
• Apache HcpComponents should be imported per NSF.
• Time-outs and service hiccups should be considered
• Values should always be cached!

#engageug
Language Preference
• Using SDK/Wrapper
• Saves Cme and eﬀort
• Ower provided and supported by the vendor/community.
• Box, IBM Watson, Salesforce, Quickbooks, etc.
• AdapCng to Domino
• CompaCbility issues.
• Java version mismatch (prior to v9.0.1 FP9), Java security
issues, etc.

#engageug
Language Preference
• Lotusscript
• No internal support for Networking…
• On Windows plaporm, we can use COM objects
• Call Java via LS2J
N O M O R E !

#engageug
New CapabiliCes of Domino v10!
• Create HTTP requests…
• NotesHTTPRequest
• Manipulate JSON…
• NotesJSONNavigator
• NotesJSONElement
• NotesJSONArray
• NotesJSONObject

#engageug
NotesHTTPRequest
• GET
• POST
• PUT
• PATCH (V10.0.1)
• DELETERESOURCE (V10.0.1)
• Preferstrings
• False: As Byte Array
• True: As Text

#engageug
Parsing JSON
• NotesJSONNavigator
• getElementByName
• getElementByPointer
• gepirstElement / getnextElement / getNthElement
• preferUTF8
• False : gets String values
• True : gets Byte Array in UTF-8
• NotesJSONElement
• NotesJSONArray

#engageug
Work has to be done
• CreateJsonNavigator causes problems with CR/LF and internaConal characters
• SoluCon=save ﬁle as UTF-8 and read as binary
• JSONNavigator doesn’t handle internaConal characters well
• Will be solved by FP2.
• Only JSON parsing, No creaCon of JSON (yet?)
• AlternaCve: ls.snapps.json… libraries
• No REST compliant Agent NotaCon
• Makes it less suitable for Providing REST services

#engageug
Consuming RESTful Services
Usage Examples
XPages 
Java - SSJS
Through SSJS or Java beans
Call when needed
Sending message to Slack
Integrations to IBM Watson
Social Media Interaction
Agents
Java - Lotusscript
Scheduled agents
Call by Notes Client
Periodically pulling exchange rates
Pushing data to remote service
Training IBM Watson AI
Using SDKs
Access to services using libraries
Call when needed
Schedule / Trigger
Accessing IBM Connections
Integration to Box

#engageug
Slide-storming on Details

#engageug
Architecture…
RESTful Remote
Web Browser
Domino Server
Web App
Agents
XPages
Notes Client
On Demand REST Conversation
Scheduled REST Conversation
On Demand
REST Conversation
On Demand
REST Conversation

#engageug
Architecture Decision…
• Who iniCates a RESTful conversaCon? When? How?
• Trigger: On demand vs. Schedule vs. Event-based
• How dynamic is the remote data? Can we use caching?
• The remote can be accessed by the server or the client?
• Intranet services cannot be accessed by remote users.
• What about security? Who has the password for the remote?
• SSO / OAuth can be a challenge in many cases.
• Predeﬁned credenCals might be exposed in some cases.

#engageug
AuthenCcaCon
• Key quesCon, depending on the remote service.
• Who is going to be authenCcated and how?
• Predeﬁned credenCal or applicaCon key
• Single Sign-on
• Users’ own credenCals on remote (OAuth, Password…)

#engageug
Some Tweaks
• SSL Issue
• TLS 1.2 is required in most cases.
• Technote: hcps://www-01.ibm.com/support/docview.wss?
uid=swg21985289
• HTTP Proxy/Gateway
• Proxy through the Domino Server for CSJS requests (Mostly for security)
• OpCons
• IBM Domino provides HTTP-proxy servlet
• ProgrammaCcally create a gateway using “Remote Service” component
• TesCng
• Postman / MockBin / RequestBin / hcpbin / JSON View

#engageug
Resources
• Serdar Başeğmez: Node.js demo for this session 
hcps://github.com/sbasegmez/Engage19Demo
• Tom Van Aken: Rest calls and JSON Parsing in LotusScript 
hcps://vanakentom.wordpress.com/2019/01/15/rest-calls-and-json-parsing-in-lotusscript/
• Serdar Başeğmez: Demo for IBM Connect 2017 session 
hcps://github.com/sbasegmez/IC17RestDemo
• Serdar Başeğmez: Apache Wink Template and Demo for Icon UK 2016 
hcps://github.com/sbasegmez/RestAssuredDemo
• Graham Acres / Serdar Başeğmez: The Journey to Becoming a Social ApplicaCon Developer (IBM Connect 2014) 
hcps://speakerdeck.com/sbasegmez/bp308-the-journey-to-becoming-a-social-applicaCon-developer
• Stephan H. Wissel: Custom REST service in XPages using a service bean 
hcps://wissel.net/blog/d6plinks/SHWL-9Q55QL

#engageug
Resources (cont.)
• Eric McCormick: Series on JSON Data with Java in XPages 
hcps://edm00se.io/json-with-java-in-xpages
• Thomas Ladehoff: REST Services with the XPages Extension Library 
hcps://www.assono.de/blog/d6plinks/REST-Services-with-the-XPages-Extension-Library
• Paul Withers: XPages OSGi Plugins series 
hcp://www.intec.co.uk/xpages-osgi-plugins-1-an-introducCon/
• John Cooper: Domino OSGI (Part 1) - Configuring Eclipse for XPages OSGI Plugins 
hcp://developmentblog.johnmcooper.co.uk/2014/05/configuring-eclipse-for-xpages-osgi-plugins-part1.html
• Toby Samples: JAX-RS or THE way to do REST in Domino series 
hcps://tobysamples.wordpress.com/2015/04/28/jax-rs-or-the-way-to-do-rest-in-domino-part-1/
• Jesse Gallagher: Eclipse Tutorial for Domino Developers 
hcps://github.com/jesse-gallagher/eclipse-tutorial-oct2015/wiki/Java

#engageug
Resources (cont.)
• Ulrich Krause: NotesJsonNavigator, NotesJsonElement, NotesJsonArray, NotesJsonObject example 
hcps://www.eknori.de/2019-01-01/notesjsonnavigator-notesjsonelement-notesjsonarray-notesjsonobject-example/
• John Dalsgaard: REST Services in IBM Domino/XWork 
hcps://www.dalsgaard-data.eu/blog/rest-services-in-ibm-dominoxwork
• Oliver Busse: First dive into Domino and Node.js 
hcp://oliverbusse.notesx.net/hp.nsf/blogpost.xsp?
documentId=2E52&SessionID=00997C8066130BED21F9B372F01DADDA32214EAE
• Oliver Busse: Domino, Proton, IAM, OAuth (Series) 
hcp://oliverbusse.notesx.net/hp.nsf/blogpost.xsp?documentId=2FEA
• Sven Hasselbach: node.js, domino-db & Docker 
hcp://hasselba.ch/blog/?p=2670
• Jesse Gallagher: That Java Thing, Part 1: The Java Problem in the Community 
hcps://frosCllic.us/blog/thread.xsp?thread=That+Java+Thing

#engageug
Resources (cont.)
• Graham Acres / Heiko Voigt: Engage 2019 Demo of Domino v10, Proton and Node.js session  
hcps://github.com/c3ug/engage2019democode
• Troy Reimer: OpenNTF Project: LotusScript implementaCon of a reader and writer for JSON 
hcps://opennp.org/main.nsf/project.xsp?r=project/JSON%20LotusScript%20Classes

#engageug
Thank you
Serdar Basegmez
Developi
serdar_basegmez
serdar.basegmez@developi.com
lotusnotus.com
Tom Van Aken
GroupWave
vanakentom
tom.vanaken@groupwave.be
vanakentom.wordpress.com

Engage 2019: Your Data in the Major Leagues: A Practical and Updated Guide to RESTful Domino v10

More Related Content

What's hot (20)

Similar to Engage 2019: Your Data in the Major Leagues: A Practical and Updated Guide to RESTful Domino v10 (20)

More from Serdar Basegmez (13)

Recently uploaded (20)

Engage 2019: Your Data in the Major Leagues: A Practical and Updated Guide to RESTful Domino v10