Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

REST services and IBM Domino/XWork - DanNotes 19-20. november 2014

4,264 views

Published on

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

Published in: Technology
  • Be the first to comment

REST services and IBM Domino/XWork - DanNotes 19-20. november 2014

  1. 1. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 REST services and IBM Domino/XWork A presentation for DanNotes by John Dalsgaard
  2. 2. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  3. 3. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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 since 1998.
  4. 4. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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”:
  5. 5. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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:
  6. 6. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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?????
  7. 7. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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... :-)
  8. 8. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 ”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
  9. 9. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 ”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
  10. 10. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 ”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 to be sent via a request (HTTP POST) ● Example – RESTful web-service: http://www.acme.com/phonebook/UserDetails/12345 – … just a URL!! (HTTP GET) – simple....
  11. 11. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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.
  12. 12. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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...
  13. 13. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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"} ]}
  14. 14. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  15. 15. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 JSON and JavaScript var text = ”{ 'name' : 'DanNotes', current : 52 }”; ● Create an object: – var danNotes = JSON.parse(text); ● Create text representation of an object: – var danNotesText = JSON.stringify(danNotes); ● Refer to attributes: – var name = danNotes.name; ● Add another attribute: – danNotes['venue'] = 'Korsør'
  16. 16. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Domino/XWork – out of the box ● Webservices (SOAP, XML, etc...) – Consumer (client) – since 8.0 – Provider (server) – since 7.0 But for now: 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
  17. 17. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  18. 18. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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)
  19. 19. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Check DAS Open: server.dom.dk/api – lists service and their state
  20. 20. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Enable data service ● On Internet site document (configuration tab): ● Need to refresh http to take effect – tell http refresh
  21. 21. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 DAS: List all ”services” (db's) ● Open: server.dom.dk/api/data
  22. 22. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 DAS: Open a specific database ● Try: server.dom.dk/reports.nsf/api/data/collections → We need to enable DAS for the database
  23. 23. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 DAS: Enable for database ● On the advanced properties of the database: ● Select level in ”Allow Domino Data Service”: ● Important decision: Views and/or documents
  24. 24. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 DAS: Open database again ● Try: server.dom.dk/demo/json.nsf/api/data/collections
  25. 25. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  26. 26. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  27. 27. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 DAS: Open a document ● Try: server.dom.dk/.../documents/unid/33735D0BC... ● Requires ”Views and documents” to be set in DB props.
  28. 28. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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”
  29. 29. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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....
  30. 30. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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....
  31. 31. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  32. 32. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 DAS: Calendar service ● There is a catch to enable this service... – In the internet site document you have to type ”Calendar” as an option.... - it is not predefined
  33. 33. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  34. 34. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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!
  35. 35. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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!!
  36. 36. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  37. 37. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  38. 38. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  39. 39. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  40. 40. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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!!)
  41. 41. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Build your own... ● One use case: – 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
  42. 42. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  43. 43. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Demo... ● Server: – Local VM with Domino 9.0.1FP1 on CentOS 6.6 – Extension Library (from IBM) – OpenNTF Domino API installed – OpenNTF Essentials installed ● A demo database – Showing an MVC pattern I use – Added a number of JSON demos – Will be made available for download ● Tool for testing: – Google Chrome Postman
  44. 44. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Demo... ● DAS – core – data – calendar ● Extension Library REST Service ● Build you own – Built-in JSON classes – GSON based on Java objects – LotusScript... ● Download DB from Bitbucket.org
  45. 45. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Live DEMO
  46. 46. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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 ;-)
  47. 47. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 Questions?? ● Did you learn something? ● Could you use it? ?
  48. 48. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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
  49. 49. © 2014, Dalsgaard Data A/S DanNotes, 19-20 November 2014 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

×