REST services in Domino - Domino Access Services Domino Programmability Team © 2012 IBM Corporation Agenda 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 2 © 2013 IBM Corporation Why REST – REST Basics 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 3 © 2011 IBM Corporation © 2013 IBM Corporation Why REST – RESTful Domino 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 © 2013 IBM Corporation REST vs SOAP Both are web services, but ... 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 5 © 2013 IBM Corporation What is Domino Access Services (DAS)? 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 6 © 2013 IBM Corporation Domino Access Services (DAS) is also a framework One framework for adding REST services to Domino Extensible framework built on Apache Wink (see http://incubator.apache.org/wink) and OSGi 7 © 2013 IBM Corporation DAS in API Framework 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 8 © 2013 IBM Corporation Domino Access Services Architecture 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. © 2011 IBM Corporation 9 © 2013 IBM Corporation Domino Access Services (DAS) Domino data service Calendar service Mail service Other services we are discussing © 2013 IBM Corporation Domino Data Service – Overview 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 11 © 2013 IBM Corporation Domino Data Service – Functionality Reading database collection Reading/updating view/folder entry collection Creating new documents Reading/updating/deleting existing documents 12 © 2013 IBM Corporation Domino Data Service Sample– GET 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" }, 13 © 2013 IBM Corporation Calendar Service - Overview Planned for 9.x Higher level of abstraction for access to calendar data JSON and iCalendar representations CRUD operations with implicit scheduling 14 © 2013 IBM Corporation Calendar Service – Functionality 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 15 © 2013 IBM Corporation Calendar service example – Read a range of events 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": {...} }, ... ] } 16 © 2013 IBM Corporation Calendar service example – Read a range of events 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 17 © 2013 IBM Corporation Calendar service example – Create a new event 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 } } ] } 18 © 2013 IBM Corporation Calendar service example – Create a new event 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 19 © 2013 IBM Corporation Mail Service – Overview and Functionality On OpenNTF now; no firm plans for product release JSON and MIME representations Read views, folders & messages; Send messages; Draft messages 20 © 2013 IBM Corporation Mail service example – Get 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..." } ] 21 © 2013 IBM Corporation Calendar service example – Get a message in JSON 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":"<font size=2 color=red face=\"sans-serif\"><b>This text is bold and red.<\/b><\/font>\r\n<br>\r\n<br>", "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\"" } ] } 22 © 2013 IBM Corporation Calendar service example – Get a message in MIME 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: <OFD02D492E.423DBF5F-ON85257961.006C242C-85257961.006C4A7F@LocalDomain> 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" <font size=2 color=red face="sans-serif"><b>This text is bold and red.</b></font> <br> --=_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_=-- 23 © 2013 IBM Corporation Other services we're discussing ● FreeBusy ● Rooms & Resources ● Traveler admin ● Looking for customer feedback on other ideas and priorities 24 © 2013 IBM Corporation