Qin Shuang

Domino Programmability Team

REST services in Domino -

Domino Access Services

3

Agenda

• Why REST?

‒ REST Basics

‒ RESTful Domino

• Domino Access Services Overview

• Domino Access Services

‒ Domino data service

‒ Calendar service

‒ Mail service

‒ Free busy service

• Enable Domino Access Services

• Build customized service

• API by release

• Reference

Why REST – REST Basics

© 2011 IBM Corporation 4

• What is REST?

‒ An new way to build API

‒ An architectural style not standard

‒ 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

‒ Most public APIs for web development are REST API

‒ Google, Twitter, Facebook,Amazon...all public their REST API

Why REST – RESTful Domino

• Domino works as service provider

‒ Client and server are more decoupled

‒ Easy to build applications

‒ 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

6

REST vs SOAP

• Both are web services, but ...

• Resource based vs Method based

• 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

7

What is Domino Access Services (DAS)?

• Growing family of REST services including:

‒ Domino data service

‒ Mail service

‒ Calendar service

‒ ...

• 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

8

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

Customer solutions using C

/ C++

Customer solutions using

REST

Customer solutions using

SSJS

JS Wrappers REST Service

Domino Access Services Architecture

© 2011 IBM Corporation

9

Domino Server

DAS Servlet

Domino Web Engine (native code)

...

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

• Free busy service

11

Domino Data Service – Overview

• Released in 8.5.3 Upgrade Pack 1; buildin 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

12

Domino Data Service – Functionality

• Reading database collection

• Reading/updating view/folder entry collection

• Creating new documents

• Reading/updating/deleting existing documents

13

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" },

Domino Data Service Sample– GET

14

Calendar Service - Overview

• Planned for 9.0.1

• Higher level of abstraction for access to calendar data

• JSON and iCalendar representations

• CRUD operations with implicit scheduling

15

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

16

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": {...}

}, ...

]

}

17

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

18

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

}

}

]

}

19

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

20

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

21

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..." } ]

Mail service example – Get messages

22

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\"" } ] }

Mail service example – Get a message in

JSON

23

Method: GET Resource: Messages URI: http:{host}/{database}/api/mail/messages/{UNID}?format=mime

MIME-Version: 1.0 To: Dan Misawa@notesdev.ibm.com 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: fadams@explorer.swg.usma.ibm.com From: fadams@notesdev.ibm.com 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_=--

Mail service example – Get a message in

MIME

24

Free busy Service – Overview and Functionality

• On OpenNTF now; no firm plans for product release

• JSON and iCalendar representations

• Find busy time for a given user, find an available room for a given time slot

25

Method: GET Resource: Busy time for a given user URI: /api/freebusy/busytime?name=deanmelnyk@swg.usma.ibm.com&format=icalendar

BEGIN:VCALENDAR BEGIN:VFREEBUSY DTSTAMP:20130513T180114Z DTSTART:20130513T173114Z DTEND:20130612T173114Z FREEBUSY:20130513T173114Z/20130513T173800Z FREEBUSY:20130513T180000Z/20130513T190000Z FREEBUSY:20130612T173500Z/20130612T173914Z END:VFREEBUSY END:VCALENDAR

Free busy service example – Busy time

26

Method: GET Resource: Free rooms URI: /api/freebusy/freerooms?site=Boston%20Building%201&start=2013-06-01T13:00:00Z&end=2013-06-01T14:00:00Z}

{ "rooms": [ { "displayName": "Room 1001", "distinguishedName": "Room 1001/Boston Building 1", "email": "bos1-room1001@swg.usma.ibm.com", "capacity": 10 }, { "displayName": "Room 1002", "distinguishedName": "Room 1002/Boston Building 1", "email": "bos1-room1002@swg.usma.ibm.com", "capacity": 8 } ] }

Free busy service example – Free Rooms

27

Enabling DAS 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" }

28

Enabling Data service for a database

• Application developer controls Database access:

• Application developer controls View access:

View Advanced Properties

Database Advanced Properties

29

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

30

APIs by Release

31

Documentation and other references

32

Thanks