rest services in domino - domino access services

© 2012 IBM Corporation

REST services in Domino -Domino Access Services

Domino Programmability Team

2 © 2013 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


Why REST – REST Basics

© 2011 IBM Corporation3

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


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


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


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


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

http://incubator.apache.org/wink



DAS in API Framework

C SDK

Java Wrappers LotusScript Wrappers

Core function

Back-end Classes

Customer solutions using

LotusScript

Customer solutions using Notes Java API


C / C++


REST


SSJS

JS Wrappers REST Service


Domino Access Services Architecture


9

Domino Server

DAS Servlet

Domino Web Engine(native code)

...Data Service Plug-in

Calendar Service Plug-in

Traveler Admin Plug-in

Apache Wink Runtime

Client can be a browser, native mobile app, etc – anything that can send an HTTP request.

All components in blue are OSGi plug-ins (Java code).


Domino Access Services (DAS)

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


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


Domino Data Service – Functionality

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


Method: GETResource: View EntriesURI: 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" },

Domino Data Service Sample– GET


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


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


Calendar service example – Read a range of events

GET http://{host}/{db}/api/calendar/eventsJSON 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": {...} }, ... ]}


Calendar service example – Read a range of events

GET http://{host}/{db}/api/calendar/events?format=icalendariCalendar response

BEGIN:VCALENDARX-LOTUS-CHARSET:UTF-8VERSION:2.0BEGIN:VEVENTDTSTART:20130203T233000ZDTEND:20130204T030000ZSUMMARY:Super Bowl XLVIILOCATION:New OrleansUID:8A3941390301436885257AD700661DAEX-LOTUS-SUMMARYDATAONLY:TRUEEND:VEVENTBEGIN:VEVENTDTSTART:20130205T140000ZDTEND:20130205T150000ZSUMMARY:Repeating AppointmentLOCATION:testUID:09C4206D7BD743D685257AB0007BA513X-LOTUS-SUMMARYDATAONLY:TRUEEND:VEVENT...END:VCALENDAR


Calendar service example – Create a new event

POST http://{host}/{db}/api/calendar/eventsContent-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 } } ]}


Calendar service example – Create a new event

POST http://{host}/{db}/api/calendar/eventsContent-Type: text/calendar

iCalendar request

BEGIN:VCALENDARVERSION:2.0PRODID:-//Some Company//NONSGML Some Product//ENBEGIN:VEVENTDTSTART:20130415T130000ZDTEND:20130415T190000ZSUMMARY:2013 Boston MarathonLOCATION:Hopkinton to BostonEND:VEVENTEND:VCALENDAR


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


Method: GETResource: InboxURI: 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..." }]

Mail service example – Get messages

Method: GETResource: MessagesURI: 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\"" } ]}

Calendar service example – Get a message in JSON

Method: GETResource: MessagesURI: http:{host}/{database}/api/mail/messages/{UNID}?format=mimeMIME-Version: 1.0To: Dan [email protected]: Message with rich text conent and attachment.Message-ID: <OFD02D492E.423DBF5F-ON85257961.006C242C-85257961.006C4A7F@LocalDomain>Date: Fri, 9 Dec 2011 14:42:49 -0500Sender: [email protected]: [email protected]: 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_=--

Calendar service example – Get a message in MIME


Other services we're discussing

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


Enabling service on server is required DAS is disabled by default. Can be enabled for Server, Database (View and Document), and View

Administrator controls which servers run the data service:

Internet Site or Server Document

{ "code":403, "text":"Forbidden", "message":"Database not allowed for Web Access"}


Enabling service for a database

Application developer controls Database access:

Application developer controls View access:

ViewAdvancedProperties

DatabaseAdvanced Properties


Custom REST Services

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 (1 of 3)

Data service : Document Repository

User storyUser want to read/write document in domino server on mobile or web browserPro-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 dominoSolutionAfter we public RESTful service, any vendor or partner can develop client application product or integrate this service into their product


User story (2 of 3)

Mail service : Social mail/Connection mail

User storyUser want to read his mail on mobile or web browserPro-art and limitationiNotes, use internal domino api instead of consume REST mail service. Additional library needed on server.SolutionREST 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 (3 of 3)

Calendar service : General calendar

User storyUser want to check his calendar on mobile, this calendar is collection for all his calendar events, including google calendar, notes calendar, iCalendar on macPro-art and limitationN/ASolutionAfter we public RESTful service, any vendor or partner can develop client application product or integrate this service into their product


APIs by ReleaseAPI Name 8.5.3 Upgrade

Pack 1Extension

Library (OpenNTF)

9.0 Social Edition

9.x

Domino data service Yes Yes In Plan In Plan

Calendar service No No No In Plan

Mail service No Yes No Not in Plan


Documentation and other referencesTopic 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/E1B347B6A993144186257AC6005577F2/%24file/Domino%20Mail%20Service.pdf

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

Domino application development in general

App Dev Wiki http://www-10.lotus.com/ldd/ddwiki.nsf

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