REST services in Domino - Domino Access Services

Full text

(1)

© 2012 IBM Corporation

REST services in Domino

-Domino Access Services

(2)

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

(3)

Why REST – REST Basics

© 2011 IBM Corporation 3

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

(4)

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

(5)

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

(6)

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

(7)

Domino Access Services (DAS) is also a framework

One framework for adding REST services to Domino

Extensible framework built on Apache Wink (see

(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

(9)

Domino Access Services Architecture

© 2011 IBM Corporation 9

Domino Server

DAS Servlet

Domino Web Engine

(native code)

...

Data Service Plug-in

Calendar

Service Plug-in Admin Plug-inTraveler

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).

(10)

Domino Access Services (DAS)

Domino data service

Calendar service

Mail service

(11)

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

(12)

Domino Data Service – Functionality

Reading database collection

Reading/updating view/folder entry collection

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

(14)

Calendar Service - Overview

Planned for 9.x

Higher level of abstraction for access to calendar data

JSON and iCalendar representations

(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

(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

(20)

Mail Service – Overview and Functionality

On OpenNTF now; no firm plans for product release

JSON and MIME representations

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

]

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

(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

(24)

Other services we're discussing

● FreeBusy

● Rooms & Resources ● Traveler admin

(25)

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"

}

(26)

Enabling service for a database

Application developer

controls

Database

access:

Application developer

controls

View

access:

View Advanced Properties Database Advanced Properties

(27)

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

(28)

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

(29)

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

(30)

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

(31)

APIs by Release

API Name 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

(32)

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

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

Figure

Updating...

Related subjects :