Microsoft 2016 2/11/2018 10: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.

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

Overview

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

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

Modern API Basics – API Endpoints Microsoft Graph: Worldwide except China: https://graph.microsoft.com China: https://microsoftgraph.chinacloudapi.cn Outlook REST API: Office 365 Multi-Tenant: https://outlook.office.com/api China: https://partner.outlook.cn/api Office 365 Dedicated: Per-customer URL.

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.

Modern API Basics - Addressing Addressing a user User’s mailbox: <API endpoint>/<Version>/users/meganb@contoso.com/ 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: <email address of the mailbox you are accessing> Note: Mailbox you are accessing may not be the same as signed in user’s mailbox

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.

Demo: Outlook on iOS Venkat Ayyadevara

Microsoft Graph

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 https://graph.microsoft.com/ © 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.

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

Today’s world with Microsoft Graph (https://graph.microsoft.com/) Work and school Personal …

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

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

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

Demo: Web App built on Graph Graph Explorer Deepak Singh

Outlook REST API Endpoint

Microsoft Graph & Outlook REST API Endpoint https://outlook.office.com/api

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

Microsoft Graph & Outlook API Endpoints Microsoft Graph proxies request to Outlook API endpoint https://graph.microsoft.com/v1.0 proxies to https://outlook.office.com/api/v2.0 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.

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.

Demo: Outlook OAuth Sandbox Outlook Task APIs Deepak Singh

What’s New with the APIs

Microsoft Graph Hybrid Exchange Support Cloud User 6 On-Premises User 1 https://graph.microsoft.com/v1.0/ 4 5 2 3 https://outlook.office.com/api/v2.0 https://mail.contoso.com/api/v2.0 AAD https://.../autodiscover/autodiscover.json Exchange Online Azure Active Directory On-Premises Exchange 2016

Microsoft Graph Hybrid Exchange Support Cloud User 8 On-Premises User 1 https://graph.microsoft.com/v1.0/ 7 2 3 4 5 6 https://outlook.office.com/api/v2.0 https://mail.contoso.com/api/v2.0 AAD https://.../autodiscover/autodiscover.json Exchange Online Azure Active Directory On-Premises Exchange 2016

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

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.

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 users @mentioned 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.

Design Considerations

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.

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

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

What’s Next

Delegate & Shared Mailbox Access w/ User Consent Request example Signed in as meganb@contoso.com X-AnchorMailbox: BenW@Contoso.com GET https://graph.microsoft.com/v1.0/users/BenW@Contoso.com/calendar/events 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: MeganB@Contoso.com GET https://graph.microsoft.com/beta/me/calendars Sharing properties: CanShare, CanViewPrivateItems, IsShared, IsSharedWithMe, CanEdit, Owner

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 https://outlook.office.com/api/beta/$batch New Batching API for daemon apps POST https://outlook.office.com/api/beta/users/meganb@con/$batch Streaming notifications

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

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!

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. 28 12: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. 29 12: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 A315-316 BRK2259 Build custom applications with Microsoft OneNote Fri, Sep. 30 9:00 AM - 10:15 AM

Wrap Up

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 http://stackoverflow.com/questions/tagged/microsoftgraph API doc issues https://github.com/OfficeDev/microsoft-graph-docs/issues User Voice for everything else https://officespdev.uservoice.com/ Outlook REST API http://stackoverflow.com/questions/tagged/outlook-restapi

Deploy, ramp-up on new services and onboard new users with Microsoft FastTrack: http://fasttrack.microsoft.com/

Join the Microsoft Tech Community to collaborate, share, and learn from the experts: http://techcommunity.microsoft.com

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

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