Build Intelligent mail, contacts and calendar apps using the Outlook REST APIs
Andrew Davidoff
Senior Software Engineer Agenda • General Overview • Microsoft Graph & Outlook API endpoints • Usage details • What’s new with the 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 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 • Microsoft Graph • 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. • Documentation • Graph APIs: https://graph.microsoft.io/en-us/docs/ • China endpoint details: https://graph.microsoft.io/en-us/docs/overview/deployments Modern API Basics – Versioning
• Version is explicitly mentioned in the path: •
• Production version is
• Beta version is
• Addressing a user • User’s mailbox:
• Addressing a group • Group: …/groups/
Single API for: https://graph.microsoft.com/ 1.Accessing data /me, /users, /groups, /messages, /drive, …. 2.Traversing data /drive/items/
Work and school Personal
• Many different APIs to access data • Separate authentication stacks for work and personal Today’s world with Microsoft Graph
Microsoft Graph https://graph.microsoft.com/
Work and school Personal
… Benefits to 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 Outlook Entities & Capabilities on Graph /v1.0
• Mail • Profile • Mail folders • User profile per AAD • Messages including Event Message • Profile picture • Item & file attachments
• Calendar • Mailbox Settings • Calendar groups & Calendars • Automatic replies • Events & Calendar view • Language & Time zone • Reminders & Reminder view
• Contacts • Data extensibility • Contact folders & Contacts • Extensions • Extended properties • Groups • Conversations, threads, posts • Capabilities • Calendar, events • CRUD • Webhooks Outlook REST API Endpoint Microsoft Graph & Outlook REST API Endpoint
https://outlook.office.com/api https://partner.outlook.cn/api Additional Entities & Capabilities on Outlook API /v2.0 /beta • Outlook Tasks • Capabilities • Task groups • Streaming notifications • Task folders • Batching API when signed in as • Tasks user
• Capabilities • Sync folder hierarchy • Delta sync 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 be 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 Production Endpoint Operation Service endpoint or Preview? 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 Microsoft Get my calendar GET v1.0/me/calendar Graph v1.0 Production Set my out of office reply PATCH v1.0/me/mailboxSettings/automaticRepliesSetting Get a message extension GET v1.0/me/messages/
Microsoft Get people related to me GET beta/me/people Graph beta Preview Find meeting times POST beta/me/findMeetingTimes Outlook API Batch multiple APIs POST beta/$batch beta Streaming notifications POST beta/Me/GetNotifications Sample application: Meeting Manager GitHub: Interop-REST-Mail-Contacts-Calendar-Sample How to use Microsoft Graph APIs
• You call resource URLs using one of operations permitted on the resource: • GET • POST • PATCH • PUT • DELETE • All Microsoft Graph API requests use the following basic URL pattern: • https://graph.microsoft.com/{version}/{resource}?[odata_query_parameters] • Summary of common requests available in the Overview • http://graph.microsoft.io/GraphDocuments/en-us/overview/overview.htm Sample Meeting Manager Application
• Available on GitHub • https://github.com/OfficeDev/Interop-REST-Mail-Contacts-Calendar- Sample • Sample code for two platforms: Android and Windows (UWP) • The sample is a real working application and can be used as starting point or a set of building blocks • Both applications log requests and responses to let you examine real-life traffic • UWP application has advanced, detailed logging Sample API Calls for Meetings and Events
• Calendar can be queried in two ways • Events for the given time period (does not expand meeting series) • Calendar view (with expanded meeting series) • Query meetings for a selected date GET https://graph.microsoft.com/v1.0/Me/calendarView?startDateTime={}&en dDateTime={}$orderby=start/dateTime • Get description of event instance or of event series GET https://graph.microsoft.com/v1.0/Me/events/{event_id} • Accept/decline event invitation POST https://graph.microsoft.com/v1.0/Me/events/{event_id}/accept Body={…} Some API Calls for Email used in the Sample
• In order to Reply To (or Forward) event message, the app first does a query for an event message that corresponds to the selected event: GET https://graph.microsoft.com/v1.0/Me/MailFolders/Inbox/messages?$filter=Subje ct eq '{subject}' and CreatedDateTime gt {event_created_datetime} • If the event message has been found, the app uses createReply, createReplyAll or createForward actions to create a draft message to be sent: POST https://graph.microsoft.com/v1.0/Me/messages/{message_id}/createreply • After user clicks Send on Email page, the app updates created message: PATCH https://graph.microsoft.com/v1.0/Me/messages/{message_id} Body = {…} • … and then sends it: POST https://graph.microsoft.com/v1.0/Me/messages/{message_id}/send DEMO Interop-REST-Mail-Contacts-Calendar-Sample (Meeting Manager) What’s New with the APIs Microsoft Graph Hybrid Exchange Support Microsoft Graph Hybrid Exchange Support Graph Entities & Capabilities for On-Premises Users
• Mail • Profile • Mail folders • User profile per AAD • Messages • Profile picture • Item & file attachments • Mailbox Settings • Calendar • Automatic replies • Calendar groups & Calendars • Language & Time zone • Events & Calendar view • Reminders & Reminder view • Data extensibility • Extended properties • Contacts • Contact folders • Capabilities • Contacts • 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 • 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. 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 Wrap Up Build Line Of Business Apps using REST APIs
• 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
API Endpoint Area URL Dev how-to questions or issues http://stackoverflow.com/questions/tagged/microsoftgraph Microsoft API doc issues https://github.com/OfficeDev/microsoft-graph-docs/issues Graph User Voice for everything else https://officespdev.uservoice.com/ Dev how-to questions or issues Outlook REST http://stackoverflow.com/questions/tagged/outlook-restapi API doc issues API User Voice for everything else https://officespdev.uservoice.com/ Thank You!
Questions?
© Microsoft Corporation. All rights reserved.