qin shuang domino programmability team - ibm · qin shuang domino programmability team rest...
TRANSCRIPT
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 [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_=--
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/[email protected]&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": "[email protected]", "capacity": 10 }, { "displayName": "Room 1002", "distinguishedName": "Room 1002/Boston Building 1", "email": "[email protected]", "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