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: • <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 to a production version usually within 3-6 months. Modern API Basics - Addressing • Addressing a user • User’s mailbox: <API endpoint>/<Version>/users/[email protected]/ • 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. Auth for Modern APIs • OAuth required. • 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. Microsoft Graph What is Microsoft Graph? Single API for: https://graph.microsoft.com/ 1.Accessing data /me, /users, /groups, /messages, /drive, …. 2.Traversing data /drive/items/<id>/lastmodifiedByUser 3.Accessing insights /insights/trending 4.Work/School and Personal State of the world before Microsoft Graph 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/<id>/extensions/<id> Get group conversations GET v1.0/groups/<id>/conversations Get my Outlook tasks GET v2.0/me/tasks Outlook API v2.0 Sync messages GET v2.0/me/mailfolders/inbox/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: