REST Services in Domino - Domino Access Services

REST services in Domino - Domino Access Services

Domino Programmability Team

 Why REST? ─ REST Basics ─ RESTful Domino  Domino Access Services Overview  Domino Access Services ─ Domino data service ─ Calendar service ─ Mail service ─ Other services we are discussing  Enable Domino Access Services  Build customized service  Some user stories  API by release  Reference

 What is REST? ─ Representational State Transfer (REST) ─ Resource-oriented: – Documents, views, messages, & calendar entries are all just resources – Each resource has a unique URL ─ Multiple representations of a resource (JSON, XML, MIME, iCalendar, etc.) ─ Uses HTTP uniform interface (GET, POST, PUT & DELETE)

 REST in the marketplace ─ Google, Facebook, Twitter all depend on REST to build market share

 Benefits of REST ─ Secure lightweight web service based on HTTP ─ Great for web applications, native mobile applications and server-to-server access

 Domino works as service provider ─ Client and server are more decoupled ─ Very low barrier to use ─ Easy to integrated in web/mobile applications

 Two ways to access REST service of Domino ─ From XPages using the REST Service control (won't cover in this slide) ─ As built-in service called Domino Access Services (DAS)

 REST API vs Traditional API ─ REST vs SOAP ─ REST vs NRPC/DIIOP

 It's easier to build a REST client ─ No need for special libraries or generated code

 REST clients are lighter ─ Easy to access a REST service by http client

REST vs NRPC/DIIOP

 Client doesn't need Notes/Domino libraries or Notes ID ─ Great for web and native mobile applications

 Growing family of REST services including: ● Domino data service ● Mail service ● Calendar service ● ...

 Access Domino data from any HTTP client

 Strategically important for integrating with other IBM products

 One framework for adding REST services to Domino

 Extensible framework built on Apache Wink (see http://incubator.apache.org/wink) and OSGi

Customer Customer solutions using solutions using Customer Customer SSJS REST solutions using solutions using Notes Java API LotusScript

JS Wrappers REST Service Customer solutions using C / C++ LotusScript Java Wrappers Wrappers

Back-end Classes

C SDK

Core function

Domino Server All components in blue are OSGi plug- Data Service Calendar Traveler ins (Java code). Plug-in Service Plug-in ... Admin Plug-in

DAS Servlet Apache Wink Runtime

Client can be a Domino Web Engine browser, native mobile (native code) app, etc – anything that can send an HTTP request.

 Domino data service  Calendar service  Mail service  Other services we are discussing

 Released in 8.5.3 Upgrade Pack 1; also planned for 9.0  Access to databases, views, folders & documents  JSON representation for easy access from JavaScript and other languages  Create, Read, Update & Delete (CRUD) operations for documents

 Reading database collection  Reading/updating view/folder entry collection  Creating new documents  Reading/updating/deleting existing documents

Method: GET Resource: View Entries URI: http:{host}/{database}/api/data/collections/unid/{unid}

[ { "@entryid":"1-0F7E8F76CACC9648852578110047D0C5", "@unid":"0F7E8F76CACC9648852578110047D0C5", "@noteid":"2C7A", "@position":"1", "Key":"AL", "Name":"ALABAMA" }, { "@entryid":"2-DF127EF6E034AFE4852578110047D0C6", "@unid":"DF127EF6E034AFE4852578110047D0C6", "@noteid":"2C7E", "@position":"2", "Key":"AK", "Name":"ALASKA" },

 Planned for 9.x  Higher level of abstraction for access to calendar data  JSON and iCalendar representations  CRUD operations with implicit scheduling

 Create, read, update and delete calendar entries  Read a range of entries from a calendar  Get a list of invitations or unapplied notices  Simple actions for calendar entries and notices  Controls for implicit scheduling

 GET http://{host}/{db}/api/calendar/events

JSON response

{ "events": [ { "id": "8A3941390301436885257AD700661DAE", "summary": "Super Bowl XLVII", "location": "New Orleans", "start": { "date": "2013-02-03", "time": "23:30:00", "utc": true }, "end": { "date": "2013-02-04", "time": "03:00:00", "utc": true } }, { "id": "09C4206D7BD743D685257AB0007BA513", "summary": "Repeating Appointment", "location": "test", "start": {...}, "end": {...} }, ... ] }

 GET http://{host}/{db}/api/calendar/events?format=icalendar

iCalendar response

BEGIN:VCALENDAR X-LOTUS-CHARSET:UTF-8 VERSION:2.0 BEGIN:VEVENT DTSTART:20130203T233000Z DTEND:20130204T030000Z SUMMARY:Super Bowl XLVII LOCATION:New Orleans UID:8A3941390301436885257AD700661DAE X-LOTUS-SUMMARYDATAONLY:TRUE END:VEVENT BEGIN:VEVENT DTSTART:20130205T140000Z DTEND:20130205T150000Z SUMMARY:Repeating Appointment LOCATION:test UID:09C4206D7BD743D685257AB0007BA513 X-LOTUS-SUMMARYDATAONLY:TRUE END:VEVENT ... END:VCALENDAR

 POST http://{host}/{db}/api/calendar/events Content-Type: application/json

JSON request

{ "events": [ { "summary": "2013 Boston Marathon", "location": "Hopkinton to Boston", "start": { "date": "2013-04-15", "time": "13:00:00", "utc": true }, "end": { "date": "2013-04-15", "time": "19:00:00", "utc": true } } ] }

 POST http://{host}/{db}/api/calendar/events Content-Type: text/calendar

iCalendar request

BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Some Company//NONSGML Some Product//EN BEGIN:VEVENT DTSTART:20130415T130000Z DTEND:20130415T190000Z SUMMARY:2013 Boston Marathon LOCATION:Hopkinton to Boston END:VEVENT END:VCALENDAR

 On OpenNTF now; no firm plans for product release  JSON and MIME representations  Read views, folders & messages; Send messages; Draft messages

Method: GET Resource: Inbox URI: http:{host}/{database}/api/mail/inbox [ { "from":"Dan Misawa", "subject":"Test sending mail...", "date":"2011-10-13T17:52:09Z", "href":"http:\/\/ibm.com\/mail\/dmisawa.nsf\/api\/mail\/messages\/969862CC4FF167B18525792..." }, { "from":"Frank Adams", "subject":"Email with Mime", "date":"2011-10-17T17:16:55Z", "href":"http:\/\/ibm.com\/mail\/dmisawa.nsf\/api\/mail\/messages\/D6BAC6EE639E5C278525792..." }, { "from":"Betty Zechman", "subject":"Message with rich text conent and attachment.", "date":"2011-12-09T18:35:43Z", "href":"http:\/\/ibm.com\/mail\/dmisawa.nsf\/api\/mail\/messages\/D02D492E423DBF5F85257961..." } ]

Method: GET Resource: Messages URI: http:{host}/{database}/api/mail/messages/{UNID} { "from":"CN=fadams\/O=Renovations", "to": ["CN=Dan Misawa \/O=Renovations"], "subject":"Message with rich text conent and attachment.", "date":"2011-12-09T19:42:49Z", "href":"http:\/\ibm.com\/mail\/dlawson.nsf\/api\/mail\/messages\/D02D492E423DBF5F85257961006C242C", "content": [ { "contentType":"multipart\/mixed; boundary=\"=_mixed 006C4A7C85257961_=\"" }, { "contentType":"text\/html; charset=\"US-ASCII\"", "data":"This text is bold and red.<\/b><\/font>\r\n
\r\n
", "boundary":"--=_mixed 006C4A7C85257961_=" }, { "contentType":"text\/plain; name=\"Text Document.txt\"", "contentTransferEncoding":"quoted-printable", "data":"This is a simple text file with some text.=\r\n=", "boundary":"--=_mixed 006C4A7C85257961_=", "contentDisposition":"attachment; filename=\"Text Document.txt\"" } ] }

Method: GET Resource: Messages URI: http:{host}/{database}/api/mail/messages/{UNID}?format=mime MIME-Version: 1.0 To: Dan [email protected] Subject: Message with rich text conent and attachment. Message-ID: Date: Fri, 9 Dec 2011 14:42:49 -0500 Sender: [email protected] From: [email protected] Content-Type: multipart/mixed; boundary="=_mixed 006C4A7C85257961_=" MIME-Version: 1.0

--=_mixed 006C4A7C85257961_= Content-Type: text/html; charset="US-ASCII"

This text is bold and red.
--=_mixed 006C4A7C85257961_= Content-Type: text/plain; name="Text Document.txt" Content-Disposition: attachment; filename="Text Document.txt" Content-Transfer-Encoding: quoted-printable

This is a simple text file with some text.= = --=_mixed 006C4A7C85257961_=--

● FreeBusy ● Rooms & Resources ● Traveler admin ● Looking for customer feedback on other ideas and priorities

 DAS is disabled by default.  Can be enabled for Server, Database (View and Document), and View { "code":403, "text":"Forbidden", "message":"Database not allowed for Web Access" }

 Administrator controls which servers run the data service:

Internet Site or Server Document

 Application developer controls Database access:

Database Advanced Properties

 Application developer controls View access:

View Advanced Properties

 Tools to build your own services using OSGi and Apache Wink ─ Java, OSGi, Wink skills required

 Apache Wink is an open source project ─ Easy to build a service in a Java servlet container ─ Uses Java annotations ─ Most of the code is contributed to Apache by the WebSphere® team ─ See http://incubator.apache.org/wink

 Enforces consistency across services – for example ● Common URL path (/api/data, /api/mail, /api/calendar) ● Common JSON error object ● Administrator uses one UI to choose what services run on a server

User story User want to read/write document in domino server on mobile or web browser Pro-art and limitation ●Xpages,Help documents on Lotus wiki are implemented by xpage, Xpages is developed and binding with db. ●Quickr,product of document repository based on domino Solution After we public RESTful service, any vendor or partner can develop client application product or integrate this service into their product

User story User want to read his mail on mobile or web browser Pro-art and limitation iNotes, use internal domino api instead of consume REST mail service. Additional library needed on server. Solution REST API is standard and general service, independent of client/server, after we provide mail service api, all kinds of web-based mail client can consume it , integrate it, including next generation notes client- Social mail

User story User want to check his calendar on mobile, this calendar is collection for all his calendar events, including google calendar, notes calendar, iCalendar on mac Pro-art and limitation N/A Solution After we public RESTful service, any vendor or partner can develop client application product or integrate this service into their product

API Name 8.5.3 Upgrade Extension 9.0 Social 9.x Pack 1 Library Edition (OpenNTF) Domino data service Yes Yes In Plan In Plan

Calendar service No No No In Plan

Mail service No Yes No Not in Plan

Topic Source Link

Domino data service App Dev Wiki http://www-10.lotus.com/ldd/ddwiki.nsf/xpViewCategories.xsp? lookupName=Domino%20Data%20Service

Mail service OpenNTF http://www.openntf.org/Projects/pmt.nsf/E1B347B6A993144186257 AC6005577F2/%24file/Domino%20Mail%20Service.pdf

Calendar service Planned for an extlib release coming soon (http://extlib.openntf.org/)

Domino application App Dev Wiki http://www-10.lotus.com/ldd/ddwiki.nsf development in general

Extension library in general OpenNTF http://extlib.openntf.org/