IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services
-
Upload
serdar-basegmez -
Category
Software
-
view
42 -
download
1
Transcript of IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services
![Page 1: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/1.jpg)
Your Data In the Major Leagues:A Practical Guide to REST ServicesSerdar BasegmezManaging Director,Developi Information Systems
DEV-1383 IBM Connect 2017 Conference, 20-23 February 2017
![Page 2: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/2.jpg)
• IBM Champion (2011 - 2017)
• Developi Information Systems, Istanbul
• OpenNTF / LUGTR / LotusNotus.com
• Featured on…
• Engage UG, IBM Connect, ICON UK, NotesIn9…
Serdar Başeğmez
![Page 3: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/3.jpg)
Agenda• RESTful Architecture
• Practical Implications
• Advantages of RESTful Services
• Providing REST Services for IBM Domino
• Consuming REST Services for IBM Domino
• Wrap-up
![Page 4: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/4.jpg)
RESTful Web Services
Representational 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 affecting the system as a whole while it is running.
Source: https://en.wikipedia.org/wiki/Representational_state_transfer
![Page 5: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/5.jpg)
History
![Page 6: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/6.jpg)
Old School Web Applications
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, JavaScriptForms →
![Page 7: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/7.jpg)
Web Applications Evolving
User Interface Business Logic Datastore
Front-end Back-end
Async web apps, Ruby on Rails, Django, JSF, XPages, etc.
← HTML, CSS, JavaScriptForms, AJAX →
![Page 8: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/8.jpg)
Web Applications Evolving
User Interface Business Logic Datastore
Front-end Back-end
Modern Web frameworks, Angular.js, React.js, etc.
← HTML, CSS, JavaScript ← REST →
![Page 9: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/9.jpg)
[Web] Applications Evolving
User Interface Business Logic Datastore
Mobile ApplicationsBack-end
Modern Web frameworks, Angular.js, React.js, etc.
← HTML, CSS, JavaScript ← REST →
Front-end
![Page 10: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/10.jpg)
[Web] Applications Evolving
User Interface Business Logic Datastore
Mobile Applications Back-end
Modern Web frameworks, Angular.js, React.js, etc.
← HTML, CSS, JavaScript
← REST →
Front-end Microservice Microservice Microservice
![Page 11: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/11.jpg)
RESTful, Everywhere!Solid Architecture
Well-defined practicesWidespread use in modern frameworks
Easily consumable, even in micro environmentsDelivers performance & scalability
![Page 12: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/12.jpg)
Stateless / Cacheable / LayeredEvery request processed independently
Client does not care who cooked the meal in the kitchenEverything cacheable
⇣Scalable, Robust, Resilient
![Page 13: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/13.jpg)
The Conversation Makes Sense!
Source: http://www.bizcoder.com/a-fresh-coat-of-rest-paint-on-a-soap-stack
![Page 14: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/14.jpg)
The Conversation Makes Sense!GET/twink/contacts/DLEY-ACLH6YHTTP/1.1Host:homer.developi.infoCache-Control:no-cache
{"zip":"13202","state":"NY","lastName":"Abbate","middle":"J","country":"US","emailAddress":"[email protected]","number":"DLEY-ACLH6Y","city":"Syracuse","firstName":"Jessica"}
![Page 15: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/15.jpg)
The Conversation Makes Sense!http://appserver.company.com/apps/contacts.nsf/
GiveMeTheContactWeNeedPleaseAgent?OpenAgent&id=1522
or…
http://appserver.company.com/api/contacts/1522
![Page 16: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/16.jpg)
Conventions on URLs
GET http://appserver.company.com/api/contacts GET http://appserver.company.com/api/contacts/UK/London
POST http://appserver.company.com/api/contacts
Retrieve Contacts / Create a new Contact…
![Page 17: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/17.jpg)
Conventions on URLs
GET http://appserver.company.com/api/contacts/1522 PUT http://appserver.company.com/api/contacts/1522
DELETE http://appserver.company.com/api/contacts/1522
Retrieve/Update/Delete the Contact resource with id=1522…
![Page 18: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/18.jpg)
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
Conventions on URLs
![Page 19: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/19.jpg)
Unconventional uses in URLs
GET https://api.twitter.com/1.1/statuses/show.json?id=1234567890
Retrieve the Tweet with id=1234567890…
![Page 20: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/20.jpg)
RESTful Servicesfor
IBM Domino Applications
![Page 21: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/21.jpg)
Some Inspiration• Alternative Front-ends
• Alternative Web Frameworks (Angular.js, React.js, etc.) / Mobile Applications
• Integration with Custom applications/services to share data and process
• Getting a list of customers from CRM, let SCM to initiate Purchase Request on Domino
• Upload a file into Box, using tone analyser from IBM Watson, send message into Slack
• Webhooks• Notify or get notified about what happened
• Other
• Enhancing In-page user experience with grids, quick searches, better type-aheads, etc.
![Page 22: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/22.jpg)
Example: Slack Bot for XSnippets
Slack Server
Slack Client
OpenNTF Server
XSnippets.nsf
XSlack REST Provider
/xsnippets[params]
MessageResponse
GETRequest FTSearch
SearchResults
MessageResponse
GEThttp://openntf.org/xsnippets.nsf/slack.xsp?text=xagentRequest:
Herearesearchresultsfor'xagent'1.ScheduledXAgent-NONSSL<http://...>2.Use@TransformtobuildJSONandconsumetheoutputinanXAgent<http://...>3.ControllingtheHTTPresponsestatuscodeinXPages<http://...>4.BuildJSONfromNotesViewwithsupportofmulti-valuefields<http://...>5.ScheduledXAgent-SSLEncrypted<http://...>
Response:
![Page 23: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/23.jpg)
Example: Box Webhooks Integration
Box Servers
Box Web
Company Server
Demo.nsf
REST ServicePOSTRequest Actions
200SuccessResponse
POSThttp://MyServer.com/MyRestServiceAddress{"source":{"name":"someFile.xyz","parent":{"name":"someFolder","type":"folder"},......},"trigger":"FILE.UPLOADED","type":"webhook_event",........}
Request:
BoxSync
UploadFileDeleteFile
Comment
![Page 24: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/24.jpg)
RESTful Services on Domino
IBM Domino Server
Web Apps Agents
IBM Notes Client
RESTful Services
As Consumer
Browser
Remote Applications
As Provider
Provider
Consumer
![Page 25: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/25.jpg)
Providing RESTful Servicesfor
IBM Domino Applications
![Page 26: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/26.jpg)
Domino Access Services• Provided and Supported by IBM
• Fully functional RESTful API for Domino Data
• Access to Views/Folders/Documents/Collections/Fields/Calendar
• Support for caching
• Mail and FreeBusy services added by ExtLib OpenNTF version
• Inherently uses standard security model (ACL, readers/authors…)
• Server-level/Database-level/Design-level control over availability
![Page 27: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/27.jpg)
Domino Access Services• No coding needed, Immediately available after a few settings.
Enable on Server Enable For Database Enable For Views
![Page 28: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/28.jpg)
Domino Access Services• Drawbacks:
• No control over the data!
• Reading a document —> Read All fields
• Creating a document —> No checkpoints!
• No place for business logic!
• What about actions? The responsibility is on the consumer
• Everything or Nothing
• Exposes internals
• You should trust consumers and the environment…
![Page 29: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/29.jpg)
REST Components (ExtLib)• Provided and Supported by IBM
• Access to Views/Folders/Documents/Collections/Fields/Calendar
• Customizable component for RESTful access• 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 routines for async access (Remote Service / JSON-RPC)
• Dojo support for single page model
![Page 30: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/30.jpg)
REST Components (ExtLib)• Setup REST component(s) on your page.
• Minimal coding, no administrator needed.
Add to your XPage Add a Service Configure Options
![Page 31: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/31.jpg)
REST Components (ExtLib)• Drawbacks:
• Careful with the code organization…
• You might inevitably end up with a spaghetti code!
• Error handling is crucial
• Prefer CustomRestService with a Java bean for more advanced stuff…
• Not optimised for performance and scalability
• Difficult to follow RESTful URL Convention
• e.g. https://someserver.domain.com/database.nsf/somepage.xsp/service/…
![Page 32: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/32.jpg)
Hardcoding (Web agents, XAgents, Servlets…)• Old school way to create services, but still quite useful for some cases.
• Great if you have pre-existing code (e.g. Lotusscript libraries, etc.)
• Customizable, flexible and simple way to create any service
![Page 33: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/33.jpg)
Hardcoding (Web agents, XAgents, Servlets…)• Drawbacks:
• Hardcode everything…
• e.g. Header/parameter extraction
• Careful with the code organization…
• You might inevitably end up with a spaghetti code!
• Error handling is crucial
• Difficult to follow RESTful URL Convention
• e.g. https://someserver.domain.com/database.nsf/xagent.xsp?…
• e.g. https://someserver.domain.com/database.nsf/someagent?OpenAgent&…
![Page 34: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/34.jpg)
Apache Wink Servlets• IBM Domino includes Apache Wink 1.1.2
• An implementation of JAX-RS
• JAX-RS: ‘Java-ish’ way to define RESTful services
• Create JAX-RS based REST services on top of OSGi plugins.
• Complete Java solution, extensible with custom providers
• Compatible with OpenNTF Domino API
• Code reusability outside IBM Domino world.
![Page 35: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/35.jpg)
Apache Wink Runtime Application Code
Apache Wink Basic Architecture
Wink Servlet(Customizable)
HTTP/HTTPS Client
Datastore
Resource
Resource
Resource
Resource
ControllersData Accessors
Tools/Utilities
Request Processor
Helpers
/BaseURI/* /BaseURI/Path-Patterns
![Page 36: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/36.jpg)
@Path("/contacts")publicclassContactResource{
privateDominoAccessoraccessor=newDominoAccessor(ContextInfo.getUserSession()); @GET() publicResponsegetContactList(@QueryParam("start")intstart,@QueryParam("count")intcount){ List<Contact>contactList=accessor.pullContacts(start,count); Stringresult=ModelUtils.toJson(contactList).toString(); returnResponse.ok(result,MediaType.APPLICATION_JSON).build(); } @Path("/{id}") @GET() publicResponsegetContact(@PathParam("id")Stringid){ Contactcontact=accessor.findContact(id);
if(null==contact){ thrownewWebApplicationException(Response.Status.NOT_FOUND); }else{ Stringresult=ModelUtils.toJson(contact).toString(); returnResponse.ok(result,MediaType.APPLICATION_JSON).build(); } }}
{"zip":"13202","state":"NY","lastName":"Abbate","middle":"J","country":"US","emailAddress":"[email protected]","number":"DLEY-ACLH6Y","city":"Syracuse","firstName":"Jessica"}
Contact Resource Class
Contact ResourceShort JSON Representation
![Page 37: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/37.jpg)
Apache Wink Servlets• Drawbacks:
• Plugin only
• Difficult if you are not familiar
• Takes time to learn
• Overkill?
• Not suitable for small projects and simple needs
• Apache Wink is old school
• Not that bad, IBM still using Wink. But Apache took another way.
• Alternatives: RESTEasy, Jersey, Apache CXF, etc.
• Integrating a new module into Domino might be an issue
![Page 38: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/38.jpg)
Providing RESTful Services on DominoBenefits Challenges Suggested When?
Domino Access Services (DAS)
No Backend CodeZero-setup
Limited ControlNo Business Logic
Exposes the InternalsSimple internal integrations
ExtLib Components for REST
Less Backend CodeMinimal Setup
Partial/Full Customization
Error HandlingSpaghetti Code Risk
URL Convention
Simple needs for a limited scope
Hardcoding (XAgents, Web agents,
Servlets)
Tailor-made(Almost) No Learning Curve
Hardcoding EverythingSpaghetti Code Risk
URL Conventions
Very specific needs for a limited scope
Apache Wink ServletsTailor-made
Based on JAX-RSOSGi Benefits
Learning CurveBarrier to Entry
Large scope implementation,
API Design
![Page 39: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/39.jpg)
Consuming RESTful Servicesfor
IBM Domino Applications
![Page 40: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/40.jpg)
How to Consume any RESTful Service?• It is just an HTTP Request…
• Questions to ask:• Lotusscript or Java or SSJS?
• On-demand or Background?
• The remote service has an SDK?
• Who is going to be authenticated?
![Page 41: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/41.jpg)
Java or SSJS or Lotusscript?• Lotusscript
• No internal support for Networking…
• On Windows platform, we can use COM objects
• Call Java via LS2J
• Server-side JavaScript
• Use Java!
• Java
• Core Java provides URLConnection class for basic operations
• Open source libraries are preferred (e.g. Apache HttpComponents)
![Page 42: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/42.jpg)
Connecting LotusScript• Pulling exchange rates (When needed or on a schedule)
Set rates = CreateObject("msxml2.DOMDocument" )
rates.async = False rates.validateOnParse = False
rates.setProperty "ServerHTTPRequest" ,True If rates.load("http://www.tcmb.gov.tr/kurlar/today.xml" ) Then
Set currencies =rates.getElementsByTagName("Currency" )
For i=0 To currencies.length - 1Set node=currencies.item(i)If node.attributes.getNamedItem("Kod").value="USD" Then
For j=0 To node.childnodes.length-1If node.childnodes.item(j).NodeName="ForexBuying" Then
forexBuyingUSD = node.childnodes.item(j).nodeTypedValueElseif node.childnodes.item(j).NodeName="ForexSelling" Then
forexSellingUSD = node.childnodes.item(j).nodeTypedValueEnd If
Next‘ Elseif for others…End If
Next
GetExchangeRates=TrueElse
GetExchangeRates=FalseEnd If
Using OLE Automation(or LS2J alternatively)
XML Parsing
Windows only!
![Page 43: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/43.jpg)
Connecting Java• Pulling exchange rates via Java (When needed or on a schedule)
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();}
}
Create an HTTP client
Get a response
Convert to JSON
* Networking is a restricted operation for Agents! Agent Security should be configured.
![Page 44: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/44.jpg)
Connecting SSJS• Pulling exchange rates on an XPage action
<xp:buttonid="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>
We can also call Java!
* This code will run multiple times for each page cycle. Always cache values!
![Page 45: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/45.jpg)
A Simple Example• Pulling exchange rates (When needed or on a schedule)
• Running from an Java Agent
• Apache HttpComponents and IBM Commons should be imported.
• Agent Security should be configured
• Running from an XPage / Java or SSJS
• Apache HttpComponents should be imported.
• Time-outs and service hiccups should be considered
• Values should always be cached!
• Lotusscript
• Platform specific vs. LS2J
![Page 46: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/46.jpg)
When/How to Connect?• Web Application triggers the RESTful conversation.
IBM Domino Server
Web AppsRESTful Service
Web Client
1. Click/Save/Update
2. REST Request
3. REST Response
4. Render Response
Latency!!!
![Page 47: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/47.jpg)
When/How to Connect?• Web Application performs the RESTful conversation at the browser.
IBM Domino Server
Web Apps
RESTful ServiceWeb Client
1. CSJS Action 2. AJAX Request
3. AJAX Response4. Process Response
Latency!!!
CORS (Cross Origin Resource Sharing)?
![Page 48: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/48.jpg)
When/How to Connect?• Notes Client performs the RESTful conversation
IBM Domino Server
Agent Manager
RESTful ServiceNotes Client
1. Run local code (Java/LS) 2. REST Request
3. REST Response
Latency!!!
4. Process Results
![Page 49: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/49.jpg)
When/How to Connect?• Notes Client performs the RESTful conversation via a Server Agent
IBM Domino Server
Agent ManagerRESTful Service
Notes Client
1. Agent.RunOnServer()
2. REST Request
3. REST Response
4. Read Results
Latency!!!
Latency!!!
![Page 50: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/50.jpg)
When/How to Connect?• RESTful conversation happens in the background
IBM Domino Server
Agent ManagerRESTful Service
1. Agent or DOTS run on a schedule
2. REST Request
3. REST Response
4. Process Results
DOTS
![Page 51: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/51.jpg)
When/How to Connect?• More complicated scenarios…
IBM Domino Server
REST ServiceRESTful Service
RESTful Consumer
1. REST Call
3. REST Request
4. REST Response
6. Return response
Latency!!!
2.Process the Request
5. Process More
![Page 52: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/52.jpg)
Why not SDK?• Many remote services provide a Java SDK or Wrapper
• Wrapper vs SDK
• Wrapper: Well-defined data model (e.g. POJO classes)
• SDK: No need to deal with low level operations
• Generally supported by the provider or the community
• But…• Compatibility issues (especially on Java Agents)
• e.g. IBM Watson SDK requires Java 7
• JVM Security issues
• Too much dependency, Poor documentation, etc.
![Page 53: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/53.jpg)
Authentication• Who is going to be authenticated and how?
• Predefined credential or application key
• Single Sign-on
• Users with their own credentials on remote (OAuth, Saved password…)
![Page 54: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/54.jpg)
Authentication• Predefined credential or application key
• Server to Server authentication
• Every REST request should be configured with proper keys
• Credential or Application key should be secured
• Not suitable for CSJS Model
![Page 55: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/55.jpg)
Authentication• Users with their own credentials on the remote system
• Single Sign-on• Valid for integrations when SSO is available (e.g. IBM Connections)
• Works within the same domain!
• The remote system expects a token, generally in cookie form
• CSJS model will work without any modification
• When HTTP request passes through the server, cookie should be transferred
![Page 56: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/56.jpg)
Authentication• Saved Password:
• Easy for the developer, but not convenient!
• Security risk, changing passwords, two-factor authentication, etc.
• Many applications do not allow credentials via API
• OAuth• Users can delegate their authentication to your application for a limited scope
• Domino has no native support, but possible with some effort (See Demo)
• IBM Social Business Toolkit SDK brings the support for OAUTH (well, sort of…)
![Page 57: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/57.jpg)
Consuming RESTful ServicesUsage Examples
XPages Java - SSJS
Through SSJS or Java beansCalled when needed
Sending message to SlackIntegrations to IBM Watson
Social Media Interaction
AgentsJava - Lotusscript
Scheduled agentsCan be called by Notes Client
Periodically pulling exchange ratesPushing data to remote service
Training IBM Watson AI
Using SDKsXPages - OSGi
Access to services using external librariesCalled when needed
Scheduled using DOTSAccessing IBM Connections
Integration to Box
![Page 58: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/58.jpg)
Demo
![Page 59: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/59.jpg)
Stackoverflow - IBM Watson Demo
![Page 60: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/60.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Web ApplicationDomino Server
0.ClientIdisneededforinitiation
https://Box_Api_Url?client_id=<App_Client_Id>&redirect_uri=<Rest_Service_Url>WewillbuildaLinktoinitiatetheflow…
TokenStore
Callback REST
![Page 61: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/61.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPageTokenStore
Callback REST
![Page 62: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/62.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPageTokenStore
Callback REST
Boxwillasktheusertologinandrequestpermissionfortheapplication.
![Page 63: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/63.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPage
2.UserAcceptedthePermissionRequest…
TokenStore
Callback REST
![Page 64: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/64.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
TokenStore
Callback REST
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPage
3.BoxIssuesaGETRequestwithatemporaryAuthenticationCode
GET
2.UserAcceptedthePermissionRequest…
![Page 65: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/65.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
TokenStore
Callback REST
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPage
3.BoxIssuesaGETRequestwithatemporaryAuthenticationCode4.WeIssueaPOSTRequestwithClientSecret+AuthenticationCode
GET
2.UserAcceptedthePermissionRequest…
POST
![Page 66: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/66.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
TokenStore
Callback REST
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPage
3.BoxIssuesaGETRequestwithatemporaryAuthenticationCode4.WeIssueaPOSTRequestwithClientSecret+AuthenticationCode5.BoxrespondswithtokensAccessToken+RefreshToken
GET
2.UserAcceptedthePermissionRequest…
POST
RES
PON
SE
![Page 67: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/67.jpg)
Browser
Box-Domino 3-legged OAuth Dance
Box Servers
Web ApplicationDomino Server
TokenStore
Callback REST
6.SaveTokens
7.DONE!
Login Page
0.ClientIdisneededforinitiation
1.RedirectUsertotheLoginPage
4.BoxIssuesaGETRequestwithatemporaryAuthenticationCode5.WeIssueaPOSTRequestwithClientSecret+AuthenticationCode6.BoxrespondswithtokensAccessToken+RefreshToken
GET
2.UserAcceptedthePermissionRequest…
POST
RES
PON
SE
Now,wecanactonbehalfoftheuser…
![Page 68: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/68.jpg)
Some Tweaks• SSL Issue
• TLS 1.2 is required in most cases.
• Technote: https://www-01.ibm.com/support/docview.wss?uid=swg21985289
• HTTP Proxy/Gateway• Proxy through the Domino Server for CSJS requests (Mostly for security reasons)
• Options
• IBM Domino provides HTTP-proxy servlet
• Programmatically create a gateway using “Remote Service” component
• Testing• REST service: Postman (Chrome Plugin / Standalone)
• REST consumer: MockBin RequestBin httpbin
![Page 69: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/69.jpg)
Wrap-up
![Page 70: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/70.jpg)
SummaryRESTful Services Architecture
Providing and Consuming RESTful services for Domino ApplicationsScenarios around RESTful Services
Architecture Examples
![Page 71: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/71.jpg)
TakeawayDownload and play with demos
Experiment simple servicesGet yourself familiar with RESTful Services
Download OpenNTF projectsStudy on RESTful design practices
Have a Pet Project
![Page 72: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/72.jpg)
Notices and disclaimers
Copyright © 2017 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission from IBM.
U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM.
Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of initial publication and could include unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT OR LOSS OF OPPORTUNITY. IBM products and services are warranted according to the terms and conditions of the agreements under which they are provided.
IBM products are manufactured from new parts or new and used parts. In some cases, a product may not be new and may have been previously installed. Regardless, our warranty terms apply.”
Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice.
Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary.
References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in which IBM operates or does business.
Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials and discussions are provided for informational purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant or their specific situation.
It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and interpretation of any relevant laws and regulatory requirements that may affect the customer’s business and any actions the customer may need to take to comply with such laws. IBM does not provide legal advice or represent or warrant that its services or products will ensure that the customer is in compliance with any law
![Page 73: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/73.jpg)
Notices and disclaimers continued
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products in connection with this publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. IBM does not warrant the quality of any third-party products, or the ability of any such third-party products to interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The provision of the information contained herein is not intended to, and does not, grant any right or license under any IBM patents, copyrights, trademarks or other intellectual property right.
IBM, the IBM logo, ibm.com, Aspera®, Bluemix, Blueworks Live, CICS, Clearcase, Cognos®, DOORS®, Emptoris®, Enterprise Document Management System™, FASP®, FileNet®, Global Business Services ®, Global Technology Services ®, IBM ExperienceOne™, IBM SmartCloud®, IBM Social Business®, Information on Demand, ILOG, Maximo®, MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower, PureAnalytics™, PureApplication®, pureCluster™, PureCoverage®, PureData®, PureExperience®, PureFlex®, pureQuery®, pureScale®, PureSystems®, QRadar®, Rational®, Rhapsody®, Smarter Commerce®, SoDA, SPSS, Sterling Commerce®, StoredIQ, Tealeaf®, Tivoli®, Trusteer®, Unica®, urban{code}®, Watson, WebSphere®, Worklight®, X-Force® and System z® Z/OS, are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at: www.ibm.com/legal/copytrade.shtml.
![Page 74: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/74.jpg)
Resources• Serdar Başeğmez: Demo for this session
https://github.com/sbasegmez/IC17RestDemo
• Serdar Başeğmez: Apache Wink Template and Demo https://github.com/sbasegmez/RestAssuredDemo
• Serdar Başeğmez: Box - SBT Demo https://github.com/sbasegmez/Blogged/tree/master/CloudFile
• Graham Acres / Serdar Başeğmez: The Journey to Becoming a Social Application Developer (IBM Connect 2014)https://speakerdeck.com/sbasegmez/bp308-the-journey-to-becoming-a-social-application-developer
• Stephan H. Wissel: Custom REST service in XPages using a service bean https://wissel.net/blog/d6plinks/SHWL-9Q55QL
• John Dalsgaard: REST Services in IBM Domino/XWorkhttps://www.dalsgaard-data.eu/blog/rest-services-in-ibm-dominoxwork
![Page 75: IBM Connect 2017: Your Data In the Major Leagues: A Practical Guide to REST Services](https://reader031.fdocuments.us/reader031/viewer/2022030306/58ce92ac1a28ab8c3b8b5c73/html5/thumbnails/75.jpg)
Resources (cont.)• Eric McCormick: Series on JSON Data with Java in XPages
https://edm00se.io/json-with-java-in-xpages
• Thomas Ladehoff: REST Services with the XPages Extension Libraryhttps://www.assono.de/blog/d6plinks/REST-Services-with-the-XPages-Extension-Library
• Paul Withers: XPages OSGi Plugins serieshttp://www.intec.co.uk/xpages-osgi-plugins-1-an-introduction/
• John Cooper: Domino OSGI (Part 1) - Configuring Eclipse for XPages OSGI Pluginshttp://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 serieshttps://tobysamples.wordpress.com/2015/04/28/jax-rs-or-the-way-to-do-rest-in-domino-part-1/
• Jesse Gallagher: Eclipse Tutorial for Domino Developershttps://github.com/jesse-gallagher/eclipse-tutorial-oct2015/wiki/Java