You are on page 1of 32

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

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

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

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

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

2013 IBM Corporation

DAS in API Framework

Customer
solutions using
SSJS

Customer
solutions using
REST

JS Wrappers

REST Service

Customer
solutions using
Notes Java API

Customer
solutions using
C / C++
LotusScript
Wrappers

Java Wrappers

Back-end Classes

C SDK

Core function

2013 IBM Corporation

Customer
solutions using
LotusScript

Domino Access Services Architecture


Domino Server
Data Service
Plug-in

Calendar
Service Plug-in

DAS Servlet

...

Traveler
Admin Plug-in

All components in
blue are OSGi plugins (Java code).

Apache Wink Runtime

Domino Web Engine


(native code)

Client can be a
browser, native mobile
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

11

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

2013 IBM Corporation

Domino Data Service Functionality

12

Reading database collection


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

2013 IBM Corporation

Domino Data Service Sample GET


Method:
Resource:
URI:

GET
View Entries
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

14

Planned for 9.x


Higher level of abstraction for access to calendar data
JSON and iCalendar representations
CRUD operations with implicit scheduling

2013 IBM Corporation

Calendar Service Functionality

15

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

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

20

On OpenNTF now; no firm plans for product release


JSON and MIME representations
Read views, folders & messages; Send messages; Draft messages

2013 IBM Corporation

Mail service example Get messages


Method:
Resource:
URI:

GET
Inbox
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:
Resource:
URI:

GET
Messages
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:
Resource:
URI:

GET
Messages
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_=--

23

2013 IBM Corporation

Other services we're discussing

24

FreeBusy

Rooms & Resources

Traveler admin

Looking for customer feedback on other ideas and priorities

2013 IBM Corporation

Enabling service on server is required

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

25

2013 IBM Corporation

Enabling service for a database

Application developer controls Database access:

Database
Advanced
Properties

Application developer controls View access:


View
Advanced
Properties

26

2013 IBM Corporation

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

27

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

2013 IBM Corporation

User story (1 of 3)
Data service : Document Repository
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

2013 IBM Corporation

User story (2 of 3)
Mail service : Social mail/Connection mail
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

2013 IBM Corporation

User story (3 of 3)
Calendar service : General calendar
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

2013 IBM Corporation

APIs by Release
API Name

31

8.5.3 Upgrade
Pack 1

Extension
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

2013 IBM Corporation

Documentation and other references


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
Planned for an extlib release coming soon (http://extlib.openntf.org/)

Calendar service

32

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/

2013 IBM Corporation

You might also like