1. Microsoft 2016
2/11/ :36 PM
BRK3046
Build Intelligent Line-of-Business Applications Leveraging the Outlook REST APIs
Venkat Ayyadevara
Program Manager
Outlook Ecosystem
@VRAyyadevara
Deepak Singh
Program Manager
Outlook Ecosystem
@Deepaksinghlko
© 2016 Microsoft Corporation. All rights reserved. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

2. Agenda Session objective Key takeaways Overview
Microsoft Graph & Outlook API endpoints
What’s new with the APIs
Design considerations for your apps & services
Sneak-peek into what is coming
Key takeaways
Powerful: APIs to create powerful applications & services to drive productivity.
Secure: Industry standard OAuth flow that respects your authentication policies.
Easy to Use: REST APIs that are easy to use on any platform you choose.
Strategic: THE APIs to use across Office 365, Hybrid Exchange 2016 & Outlook.com.
Production Ready: Available now to build production apps & services at scale

3. Overview

4. Why do the REST APIs matter?
100’s of millions of users
Office 365 & Outlook.com for production apps & services
Hybrid Exchange deployment support in preview
On-premises Exchange on our roadmap
Many of these are highly engaged Outlook users.
Powerful, intuitive way to build apps & services
Granular, tightly scoped permissions to access data
Based on open standards – OAuth 2.0, JSON & OData 4.0

5. API Landscape Modern APIs Older APIs Microsoft Graph Outlook REST API
The API to use to build apps & services integrating w/ Office services for cloud & hybrid users
Outlook REST API
Outlook/Exchange specific API endpoint to use if Microsoft Graph doesn’t have the APIs yet.
Older APIs
Exchange Web Services (EWS) SOAP APIs
Available since Exchange 2007 SP1 for integration with Exchange. No granular access.
Exchange Active Sync (EAS)
Used by mobile device manufacturers for built-in messaging client. Requires licensing.
Not intended for any other integrations including line of business apps & services

6. Modern API Basics – API Endpoints
Microsoft Graph:
Worldwide except China:
China:
Outlook REST API:
Office 365 Multi-Tenant:
China:
Office 365 Dedicated: Per-customer URL.

7. Modern API Basics – Versioning
Version is explicitly mentioned in the path:
<API endpoint>/<Version>/
Production version is <API endpoint>/vX.Y/
No breaking changes based on OData 4.0 versioning guidelines.
Fully supported for production applications & services
Latest production versions: Microsoft Graph v1.0 & Outlook REST API v2.0
Beta version is <API endpoint>/beta/
New APIs introduced in Beta to solicit feedback. Not intended for production.
Might make breaking changes based on feedback.
Promoted usually to a production version within 3-6 months.

8. Modern API Basics - Addressing
Addressing a user
User’s mailbox: <API
Shortcut for signed in user’s mailbox: <API endpoint>/<Version>/me/
Addressing a group
Group: …/groups/<id>/ where <id> is the Azure Active Directory group ID.
For Outlook REST APIs, decrease latency by adding:
X-AnchorMailbox: < address of the mailbox you are accessing>
Note: Mailbox you are accessing may not be the same as signed in user’s mailbox

9. Auth for Modern APIs OAuth required. Multiple auth flows supported
Unlike EWS, app has no access to user’s credentials.
Authentication respects your organization’s policies e.g. 2 factor auth.
Multiple auth flows supported
Open ID Connect for single sign on (SSO)
OAuth2 code flow support for interactive apps
OAuth2 client credential flow support for daemon apps
OAuth2 implicit grant flow for web apps
OAuth2 on-behalf flow for web apps
Granular consent limits exposure to faulty application & service bugs.
Unlike EWS, app can request consent for just the permission(s) it needs e.g. Calendars.Read or Contacts.ReadWrite or Mail.Send.

10. Demo: Outlook on iOS
Venkat Ayyadevara

11. Microsoft Graph

12. What is Microsoft Graph?
2/11/2018
What is Microsoft Graph?
Single API for:
Accessing data
/me, /users, /groups, /messages, /drive, ….
Traversing data
/drive/items/<id>/lastmodifiedByUser
Accessing insights
/insights/trending
Work/School and Personal
© 2014 Microsoft Corporation. All rights reserved. Microsoft, Windows, and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

13. State of the world before Microsoft Graph
Work and school
Personal
Many different APIs to access data
Separate auth stacks for work and personal

14. Today’s world with Microsoft Graph(
Work and school
Personal …

15. Benefits to Your Developers
One auth for cloud & hybrid on-premises users.
Single registration portal for commercial (cloud, on-premises) & consumer.
Single auth endpoint.
One API endpoint
No need to autodiscover the API endpoint for a user & remember it.
Build compelling views for a user joining on-prem & cloud content.
Microsoft Graph returns meaningful error for capabilities not available on on-premises server.
Easy to developer on your platform of choice
Industry standards: REST, JSON, OAuth 2.0
Microsoft Graph client libraries for multiple platforms once we exit preview
UWP
iOS
.NET
Android
Python
Ruby

16. Outlook Entities & Capabilities on Graph /v1.0
Mail
Mail folders
Messages including Event Message
Item & file attachments
Calendar
Calendar groups & Calendars
Events & Calendar view
Reminders & Reminder view
Contacts
Contact folders & Contacts
Groups
Conversations, threads, posts
Calendar, events
Profile
User profile per AAD
Profile picture
Mailbox Settings
Automatic replies
Language & Time zone
Data extensibility
Extensions
Extended properties
Capabilities
CRUD
Webhooks

17. Additional Outlook Entities on Graph /beta
Mail
@Mentions
Event Message Request
Reference Attachment
Calendar
Find Meeting Times API
Forward Event API
People
Person (read-only)
Profile
Profile pics of many sizes
Mail Tips
Automatic replies
Capabilities
Delta sync i

18. Demo: Web App built on Graph Graph Explorer
Deepak Singh

19. Outlook REST API Endpoint

20. Microsoft Graph & Outlook REST API Endpoint

21. Additional Entities & Capabilities on Outlook API
/v2.0
Outlook Tasks
Task groups
Task folders
Tasks
Capabilities
Sync folder hierarchy
Delta sync
/beta
Capabilities
Streaming notifications
Batching API when signed in as user

22. Microsoft Graph & Outlook API Endpoints
Microsoft Graph proxies request to Outlook API endpoint
proxies to
Same Outlook business logic is exercised for requests to Graph and Outlook API endpoints.
Why does Outlook endpoint offer more APIs than Graph?
Most API changes first deployed to Outlook API and then added to Graph in 1-2 months.
Sometimes, it may take longer to fill the gap in Graph because:
A capability like. batching has to generalized to work well for Graph and all its downstream services.
A concept like folder needs to be rationalized across multiple services.
We are working hard to drive down gap between Graph and Outlook API endpoints to zero.
Use Graph unless blocked by an API gap w/ Outlook API.
Using Graph makes it easy for you to leverage content and insights from multiple services.
You must use Graph to support on-premises users of Exchange hybrid deployments.

23. Sample API Requests Microsoft Ignite 2016 2/11/2018 10:36 PM
Production or Preview?
Endpoint
Operation
Service endpoint
Production
Microsoft Graph v1.0
Get my profile
GET v1.0/me
Get my profile picture
GET v1.0/me/photo/$value
Get my inbox messages
GET v1.0/me/mailFolders/inbox/messages
Get my calendar
GET v1.0/me/calendar
Set my out of office reply
PATCH v1.0/me/mailboxSettings/automaticRepliesSetting
Get a message extension
GET v1.0/me/messages/<id>/extensions/<id>
Get group conversations
GET v1.0/groups/<id>/conversations
Outlook API v2.0
Get my Outlook tasks
GET v2.0/me/tasks
Sync messages
Prefer: odata.track-changes
GET v2.0/me/mailfolders/inbox/messages
Preview
Microsoft Graph beta
Get people related to me
GET beta/me/people
Find meeting times
POST beta/me/findMeetingTimes
Outlook API beta
Batch multiple APIs
POST beta/$batch
Streaming notifications
POST beta/Me/GetNotifications
© 2016 Microsoft Corporation. All rights reserved. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

24. Demo: Outlook OAuth Sandbox Outlook Task APIs
Deepak Singh

25. What’s New with the APIs

26. Microsoft Graph Hybrid Exchange Support
Cloud User 6
On-Premises User 1 4 5 2 3
AAD
Exchange Online
Azure Active Directory
On-Premises Exchange 2016

27. Microsoft Graph Hybrid Exchange Support
Cloud User 8
On-Premises User 1 7 2 3 4 5 6
AAD
Exchange Online
Azure Active Directory
On-Premises Exchange 2016

28. Graph Entities & Capabilities for On-Premises Users
Mail
Mail folders
Messages
Item & file attachments
Calendar
Calendar groups & Calendars
Events & Calendar view
Reminders & Reminder view
Contacts
Contact folders
Profile
User profile per AAD
Profile picture
Mailbox Settings
Automatic replies
Language & Time zone
Data extensibility
Extended properties
Capabilities
CRUD

29. APIs Promoted from Beta to Production
Microsoft Graph (beta  v1.0)
MailboxSettings API to get/set a user’s automatic reply, time zone and language.
Extensions for message, event, contact and posts.
Extended Properties for message, event, contact, post, mail folder, contact folder & calendar.
Outlook REST API (beta  v2.0)
Outlook task APIs – Task groups, task folders and tasks
Tasks.Read and Tasks.ReadWrite permissions
Message delta sync APIs to sync incremental changes to mail in a specific folder.
Mail Folder hierarchy sync APIs to sync mail folder hierarchy.

30. New APIs Added in Beta Microsoft Graph Outlook REST API
MailTips API to retrieve mail tips leveraged by outlook, especially to check if a recipient is out of office.
@Mentions API to get/set in a message
New EventMessageRequest type derived from Event Message to represent a message invite. Provides info on changes from an older invite, for updated meeting invites
Forward event API to forward an event to another user
Outlook REST API
Streaming notifications APIs for client apps that don’t have a server endpoint to receive webhooks.

31. Design Considerations

32. API Considerations Extensions vs. Extended Properties
We recommend using extensions instead of extended properties unless:
Using complex properties, or
Stamping custom properties on a mail folder, contact folder or calendar.
Extended property APIs make it easier to port from EWS apps that use extended properties.
All extensions associated with an entity are available to all calling apps.
Permissions governing access to an entity also apply to its extensions.
$filter vs. $search
$filter applies a restriction on Exchange Store. Use this to generate views e.g. list view.
$search leverages search indexes maintained on Exchange server. Use this for full-text search.
Batching (/api/$batch)
You can only batch requests to a single mailbox.
OAuth token from app must contain user context, to be able to route to right mailbox.

33. Performance & Diagnostics Considerations
Tailoring requests for optimal app performance
If calling Outlook API endpoint, use outlook.office.com instead of outlook.office365.com for lower latencies.
Use X-AnchorMailbox especially for optimal routing.
Use $top, $select, $filter to narrow requests, especially $select to:
Decrease bandwidth
Avoid unnecessary processing on server to retrieve or compute expensive properties.
Use smart reply & forward to minimize bandwidth and decrease # of round trips for mobile apps.
Use notifications instead of polling. For a service, use webhooks to be notified of changes.
Throttling & Service Unavailable
Throttled response returns HTTP status code Respect Retry-After time specified in response!
Use exponential back off when dealing with “service unavailable” errors.
Add instrumentation to your app or service
Add header info like “user-agent”, “client-request-id”.
Keep a failure log for troubleshooting.
Include “client-request-id” and all HTTP response headers for a failed request.

34. Exchange Web Services (EWS) Full Feature Set Growing  OAuth Support
REST APIs
Exchange Web Services (EWS)
Full Feature Set
Growing 
OAuth Support
Granular permissions
Full access (Office 365 only)
Daemon Apps
App-only Access
App impersonation
Reach:
Office 365
On-premises Exchange
Coming to Exchange 2016
Exchange 2007 SP1 & later
Hybrid Exchange
Exchange 2016 (Preview)
Exchange 2010 & later
Outlook.com
Functionality
Mail, Calendar, Contacts & Tasks
People APIs
Preview
Apps using multiple services
One auth, one API endpoint
No interop for other service APIs
Mobile-friendly
Smart reply/forward, JSON
Verbose SOAP request/response
Batching
Batching across multiple APIs
No batching across multiple APIs
Notifications
Webhooks
Streaming notifications

35. What’s Next

36. Delegate & Shared Mailbox Access w/ User Consent
Request example
Signed in as
X-AnchorMailbox:
GET
Permissions
Mail: Mail.Read.Shared & Mail.ReadWrite.Shared
Calendar: Calendars.Read.Shared & Calendars.ReadWrite.Shared
Contacts: Contacts.Read.Shared & Contacts.ReadWrite.Shared
Tasks: Tasks.Read.Shared & Tasks.ReadWrite.Shared
Enumerate list of calendars shared by others with a user
X-AnchorMailbox:
GET
Sharing properties: CanShare, CanViewPrivateItems, IsShared, IsSharedWithMe, CanEdit, Owner

37. APIs to be Promoted from Beta to Production
Microsoft Graph (beta  v1.0)
FindMeetingTimes API
Permission: Calendars.Read.Shared or Calendars.ReadWrite.Shared
Event forwarding API
MailTips API
People API
Outlook REST API (beta  v2.0)
Batching API when signed in as user to an interactive app
POST
New Batching API for daemon apps
POST
Streaming notifications

38. New APIs to be Added in Beta
Microsoft Graph
Improved Message API support for MIME
Calendar API improvements
Option to not push group calendar updates to user’s calendar
Online meeting info such as phone numbers, in addition to online meeting URL
Complex type support for Extensions
Outlook REST API
Return partial updates in delta sync response for messages

39. Exit Preview for Hybrid Exchange Deployment
Hybrid Configuration Wizard (HCW) update
Querying per-user version & capabilities
API improvements
Ability to use /me instead of /users/<id>/
Support for notifications
Additional entities for on-premises users e.g. Extensions
Microsoft Graph SDK support
End user Graph explorer support for on-premises
Incorporate your feedback and suggestions!

40. Related Sessions Session Title Time Location BRK2157
Get the Office developer platform roadmap
Mon, Sep 26 2:15 PM - 3:30 PM
A311-A312
BRK4016
Access SharePoint files and lists using SharePoint API in Microsoft Graph API
Tue, Sep 27 2:15 PM - 3:30 PM
A411-A412
BRK3199
Access intelligence in the Microsoft Graph and API
Tue, Sep 27 4:00 PM - 5:15 PM
BRK3113
Exploit the Microsoft Graph API to supercharge your Line of Business Applications
Tue, Sep. 27 9:00 AM - 10:15 AM
A313-A314
BRK3306
Power your applications with Excel Workbooks as a Service
Wed, Sep 28 9:00 AM - 10:15 AM
A402-A403
BRK3045
Use Microsoft Graph to Reach Users on Hybrid Exchange 2016
Wed, Sep 28 10:45 AM - 12:00 PM
A302
BRK4012
Dive Deep on Skype Web SDK & Skype for Business App SDK: Build apps across Web, IOS & Android
Wed, Sep :30 PM - 1:45 PM
B304-B305
BRK2054
Empower teams with actionable mail using Office 365 Connectors in Outlook
Wed, Sep. 28 2:00 PM - 2:45 PM
A305
BRK3044
Integrate line of business services and processes with Outlook on Windows, Mac and web
Wed, Sep. 28 2:15 PM - 3:30 PM
BRK2028
Manage and deploy Office add-ins and Office 365 apps
Thu, Sep :30 PM - 1:45 PM
BRK2160
Build business applications with Power Apps, Microsoft Flow, and Office 365
BRK3114
Create cross-platform mobile apps with Xamarin that connect to Office Services
Thu, Sep. 29 4:00 PM - 5:15 PM
BRK1019
Vote and celebrate at the Microsoft Office App Awards A
BRK2259
Build custom applications with Microsoft OneNote
Fri, Sep. 30 9:00 AM - 10:15 AM

41. Wrap Up

42. Build LOB Apps using REST APIs
Key Takeaways
Powerful: APIs to create powerful applications & services to drive productivity.
Secure: Industry standard OAuth flow that respects your authentication policies.
Easy to Use: REST APIs that are easy to use on any platform you choose.
Strategic: THE APIs to use for Office 365, Hybrid Exchange 2016 & Outlook.com.
Production Ready: Available now to build production apps & services at scale
We would love to hear from you!
API Endpoint
Area
URL
Microsoft Graph
Dev how-to questions or issues
API doc issues
User Voice for everything else
Outlook REST API

43. Deploy, ramp-up on new services and onboard new users with Microsoft FastTrack:

44. Join the Microsoft Tech Community to collaborate, share, and learn from the experts:

45. Please evaluate this session
2/11/ :36 PM
Please evaluate this session
Your feedback is important to us!
From your PC or Tablet visit MyIgnite at
From your phone download and use the Ignite Mobile App by scanning the QR code above or visiting
© 2014 Microsoft Corporation. All rights reserved. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

46. 2/11/ :36 PM
© 2014 Microsoft Corporation. All rights reserved. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.