4 100’s of millions of Users Office 365 (now), Outlook.com (soon), hybrid and on-premises on our...

Rohit NagarmalProgram Manager – Microsoft Exchange

Outlook REST APIs for Developing Against Outlook.com and Office 365

3-742

Session Objectives: • Why are the Office 365 REST APIs

Important?• Drill down into the API’s• Best practices• Compare with existing API’s like EWS• Sneak-peek into what is coming

Key Takeaways:• APIs that allows you to create end to end

Office 365 apps with targeted scopes

• Lightweight and quick to learn and develop

Agenda

Why Do These REST APIs Matter?

4

• 100’s of millions of Users Office 365 (now), Outlook.com (soon), hybrid and on-premises on our roadmap

• Engaged Users

• Powerful, intuitive way to access and manipulate Office 365 data

• Granular, tightly scoped permissions to access user data

• Based on open standards – OAuth 2.0, JSON, ODATA v4.0

MICROSOFT CONFIDENTIAL – INTERNAL ONLY

What REST API’s do we offer?SharePoint

Sites

Exchange & Outlook.com

Calendar

Contacts

Mail

OneDrive

OneDrive for Business

Active Directory

Users

Groups

Client API

Search

Sites, Lists and Libs

Taxonomy

BCSWorkflow

…Unified Groups

Common Consent Framework for Office 365• Single Authentication flow for Office

365• Azure AD Graph, Exchange,

SharePoint• Device apps and web apps• Admin and end-user consent

• Secure protocol• OAuth 2.0• No capturing user credentials• Fine-grained access scopes• Supports MFA and federated user

sign-in• Long-term access through refresh

tokens

MICROSOFT CONFIDENTIAL – INTERNAL ONLY

Discovering endpoints and API’s

7

Office 365 discovery servicesAutomatically determine URL of Office 365 servicesSupports device app and website flowsSecured using Azure AD authenticationServes information stored about services in AAD

Rich service metadata Lists all Entities, Collections, Actions, Complex Types, Enums and their Properties.e.g.: https://outlook.office365.com/api/v1.0/$metadata

• .NET SDK to build many types of apps using Visual Studio.NET Windows Store AppsWindows Forms ApplicationWPF ApplicationASP.NET MVC Web ApplicationASP.NET Web Forms ApplicationXamarin Android and iOS ApplicationsMulti-device Hybrid Apps (Cordova)

• Android SDK & iOS SDK’s

Rich Tooling

• Permissions• Read, Read+Write, Send

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/v1.0/Me/Folders/Inbox• https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=1&$select=subject• https://outlook.office365.com/api/v1.0/Me/SendMail/

You’ve got Mail!

Entity Collection Actions

Folder Folders CRUD, Copy, Move

Message Messages

CRUD, Copy, Move, Reply, ReplyAll, Forward, Send, CreateReply, CreateReplyAll, CreateForward 

Attachment Attachments CRUDCollection

Entity

Intuitive Send API

• Permissions• Read, Read+Write

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/v1.0/Me/Calendar • https://outlook.office365.com/api/v1.0/Me/Calendar/Events?$top=1• https://outlook.office365.com/api/v1.0/Me/CalendarView?startDateTime=2015-01-01 &

endDateTime=2015-01-31

Calendar – Coffee @ 4?

Entity Collection Actions

CalendarGroupCalendarGroups CRUD 

Calendar Calendars CRUD 

Event EventsCRUD, Accept, Decline, TentativelyAccept

CalendarView N/A Read

Attachment Attachments CRUDCollection

Entity

No client-side recurrence

expansion required

• Permissions• Read, Read+Write

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/v1.0/Me/ContactFolders/• https://outlook.office365.com/api/v1.0/Me/Contacts/?$select=displayname

• Use AAD Graph API to find users in a tenant.

Contacts – Your number again?

Entity Collection Actions

ContactFolder ContactFolders CRUD

Contact Contacts CRUD

DemoCommon REST API Requests

• List Messages, Events, Contacts• How to filter, orderby, select properties• Paging• Send mail, reply to an email• Create meeting

Rich Query Syntax using ODataScenario URL

Get 5 messages from Inbox https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=5

Get the next 10 messages ../Me/Folders/Inbox/Messages?$top=10&$skip=5

Get top 10 messages sorted by DateTimeCreated

../Me/Folders/Inbox/Messages?$top=10&$orderby=DateTimeCreated

Get selective properties on messages

../Me/Folders/Inbox/Messages?$top=5&$select=From,DateTimeCreated,Subject

Get events starting after a particular DateTime

../Me/Events?$top=5&$select=Subject,Start,End&$filter=Start ge 2014-09-22T20:00:00Z

Get Inbox messages with subject and attachment info

../Me/Folders/Inbox/Messages?$format=application/json;odata.metadata=none&$select=Subject&$expand=Attachments

Get # of messages with attachment(s)

../Me/Folders/Inbox/Messages/$count?$filter=HasAttachments eq true

Get count and selective props on messages with attachment(s)

..Me/Folders/Inbox/Messages?$format=application/json;odata.metadata=none&$select=Subject&$filter=HasAttachments%20eq%20true&$count=true

Get contact with a given name

../Me/Contacts/?$filter=Givenname eq ‘John’

• Permissions• Groups.Read.All, Groups.ReadWrite.All

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/beta/groups/projectx@contoso.com• https://outlook.office365.com/api/beta/groups/projectx@contoso.com/

conversations

Introducing - Groups API (preview)

Entity Collection Actions

Group Groups

SubscribeByMail, UnsubscribeMyMail, AddFavorite, RemoveFavorite, ResetUnseenCount

Conversation Conversations Create, Read, Delete

Thread Threads Reply

Post Posts Reply, Forward

Attachment Attachments CRUD

Calendar/Event Events Same as ../me/calendar

Beta

DemoGroups REST API Requests

• Permissions• Uses existing Read or ReadWrite permission for Mail, Calendar, Contacts or Groups

• Supported entity collections• Messages• Events• Contacts• Groups (Unseen Count)

• Conversations• Threads• Events

• Samples• POST https://outlook.office365.com/api/beta/me/subscriptions • Group - subscription https://outlook.office365.com/api/beta/me/groups(

'mygroup@contoso.com')/subscriptions

Introducing – Webhooks (preview)

• Timezone support for events

• Full text search ($Search) messageshttps://outlook.office365.com/api/beta/me/folders/inbox/messages?$

search=foo

• Get User HD photo

• CORS support*Build Single Page Apps

Other notable new features

Demo

Search, Photo

19

Demo

Getting Started:Office 365 APIs starter Project – Visual Studio

• Provide instrumentation in your app• Add Header info like ‘user-agent’, ‘client-request-id’• Maintain a failure log for troubleshooting. • Include ‘client-request-id’ and all HTTP response headers from the

failed requests.

• Be mindful of requests that generate large responses

• Use $top, $select, $filter to narrow requests• App performance depends on it• Keep your app responsive by not getting throttled• Be conservative with refresh requests/frequent polling

Best Practices

I am confused: REST API, EWS or EAS? EWS EAS RESTFull Feature Set Limited Growing Oauth supportReach: Exchange OnlineHybrid with 2013 ComingOn Prem 2013 ComingOn Prem 2010 and 2007Outlook.com users*

Modern API:Easy Discovery and ExplorationMetadataEasy to learn and developDesigned for App developersLighter payloadGranular ConsentAPI Sandbox

Client SDKs.Net, Java

.Net, Android, iOS, JS (cordova)

Licensing

Enable end to end scenarios – web, mobile focus*

• Batching• Custom/Extended properties• Sync• Free busy• Mail tips, OOF settings• Delegate scenarios

*71% of work will be done by web based, mobile apps by 2020

Roadmap

Partners already using the API

In Review: Session Objectives And Takeaways• Session Objectives:

• Why are the Office 365 REST APIs Important?• Drill down into the API’s• Best practices• Compare with existing API’s like EWS• Sneak-peek into what is coming

• Key Takeaways:• APIs that allows you to create end to end Office 365 apps with

targeted scopes

• Lightweight and quick to learn and develop

http://dev.office.com/devprogram

Developer Program Launch

E-mail Newsletters

Free Developer Subscriptio

n

1 YEAR FREE

Free Training

Free Tools

Webinars

Call to action

Sign up for Developer Program

Collect your stickers at //build

Check out the express talks

Related sessions

728 Integrating web applications for Office 365

Online Soon

630 Get Your Hands Dirty with the Office 365 APIs, Authentication and SDKs

641 Supercharging your custom solutions with the Office 365 unified API endpoint

676 Building Solutions with Office Graph

701 Deep Dive into the Office 365 Groups REST API

632 Office 365 and Azure: A Developer's Guide for Maximizing the Cloud

722 Mobile Development with iOS, Android and Office 365

715 Connecting to OneNote in the Cloud with Office 365 APIs

661 Building Multi-Device Applications with Xamarin with Office 365 APIs

689 Building a Single Page App Using Angular and Typescript Using Office 365 APIs 10:30 AM

742Learn about Outlook REST APIs for developing apps against Office 365 and Outlook.com 10:30 AM

767 Building Universal Apps with Connected Services 02:00 PM

Session Objectives: • Why are the Office 365 REST APIs

Important?• Drill down into the API’s• Best practices• Compare with existing API’s like EWS• Sneak-peak into what is coming

Key Takeaways:• APIs that allows you to create end to end

O365 apps with targeted scopes

• Lightweight and quick to learn and develop

Agenda

Why Do These REST APIs Matter?• 100’s of millions of Users

O365 (now), Outlook.com (soon), hybrid and on-premises on our roadmap

• Engaged Users

• Powerful, intuitive way to access and manipulate O365 data

• Granular, tightly scoped permissions to access user data

• Based on open standards – OAuth 2.0, JSON, ODATA v4.0

MICROSOFT CONFIDENTIAL – INTERNAL ONLY

What REST API’s do we offer?SharePoint

Sites

Exchange & Outlook.com

Calendar

Contacts

Mail

OneDrive

OneDrive for Business

Active Directory

Users

Groups

Client API

Search

Sites, Lists and Libs

Taxonomy

BCSWorkflow

…Unified Groups

Common Consent Framework for Office 365• Single Authentication flow for O365

• Azure AD Graph, Exchange, SharePoint

• Device apps and web apps• Admin and end-user consent

• Secure protocol• OAuth 2.0• No capturing user credentials• Fine-grained access scopes• Supports MFA and federated user

sign-in• Long-term access through refresh

tokens

MICROSOFT CONFIDENTIAL – INTERNAL ONLY

Discovering endpoints and API’s

Office 365 discovery servicesAutomatically determine URL of O365 servicesSupports device app and website flowsSecured using Azure AD authenticationServes information stored about services in AAD

Rich service metadata Lists all Entities, Collections, Actions, Complex Types, Enums and their Properties.e.g.: https://outlook.office365.com/api/v1.0/$metadata

• .NET SDK to build many types of apps using Visual Studio.NET Windows Store AppsWindows Forms ApplicationWPF ApplicationASP.NET MVC Web ApplicationASP.NET Web Forms ApplicationXamarin Android and iOS ApplicationsMulti-device Hybrid Apps (Cordova)

• Android SDK & iOS SDK’s

Rich Tooling

• Permissions• Read, Read+Write, Send

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/v1.0/Me/Folders/Inbox• https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=1• https://outlook.office365.com/api/v1.0/Me/SendMail/

You’ve got Mail!

Entity Collection Actions

Folder Folders CRUD, Copy, Move

Message Messages

CRUD, Copy, Move, Reply, ReplyAll, Forward, Send, CreateReply, CreateReplyAll, CreateForward 

Attachment Attachments CRUDCollection

Entity

Intuitive Send API

• Permissions• Read, Read+Write

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/v1.0/Me/Calendar • https://outlook.office365.com/api/v1.0/Me/Calendar/Events?$top=1• https://outlook.office365.com/api/v1.0/Me/CalendarView?startDateTime=2015-01-01 &

endDateTime=2015-01-31

Calendar – Coffee @ 4?

Entity Collection Actions

CalendarGroupCalendarGroups CRUD 

Calendar Calendars CRUD 

Event EventsCRUD, Accept, Decline, TentativelyAccept

CalendarView N/A Read

Attachment Attachments CRUDCollection

Entity

No client-side recurrence

expansion required

• Permissions• Read, Read+Write

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/v1.0/Me/ContactFolders/• https://outlook.office365.com/api/v1.0/Me/Contacts/

• Use AAD Graph API to find users in a tenant.

Contacts – Your number again?

Entity Collection Actions

ContactFolder ContactFolders CRUD

Contact Contacts CRUD

DemoCommon REST API Requests

• List Messages, Events, Contacts• How to filter, orderby, select properties• Paging• Send mail, reply to an email• Create meeting

Rich Query Syntax using ODataScenario URL

Get 5 messages from Inbox https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=5

Get the next 10 messages ../Me/Folders/Inbox/Messages?$top=10&$skip=5

Get top 10 messages sorted by DateTimeCreated

../Me/Folders/Inbox/Messages?$top=10&$orderby=DateTimeCreated

Get selective properties on messages

../Me/Folders/Inbox/Messages?$top=5&$select=From,DateTimeCreated,Subject

Get events starting after a particular DateTime

../Me/Events?$top=5&$select=Subject,Start,End&$filter=Start ge 2014-09-22T20:00:00Z

Get Inbox messages with subject and attachment info

../Me/Folders/Inbox/Messages?$format=application/json;odata.metadata=none&$select=Subject&$expand=Attachments

Get # of messages with attachment(s)

../Me/Folders/Inbox/Messages/$count?$filter=HasAttachments eq true

Get count and selective props on messages with attachment(s)

..Me/Folders/Inbox/Messages?$format=application/json;odata.metadata=none&$select=Subject&$filter=HasAttachments%20eq%20true&$count=true

Get contact with a given name

../Me/Contacts/?$filter=Givenname eq ‘John’

• Permissions• Groups.Read.All, Groups.ReadWrite.All

• Entities, Collections, Actions

• Samples• https://outlook.office365.com/api/beta/groups/projectx@contoso.com• https://outlook.office365.com/api/beta/groups/projectx@contoso.com/

conversations

Introducing - Groups API (preview)

Entity Collection Actions

Group Groups

SubscribeByMail, UnsubscribeMyMail, AddFavorite, RemoveFavorite, ResetUnseenCount

Conversation Conversations Create, Read, Delete

Thread Threads Reply

Post Posts Reply, Forward

Attachment Attachments CRUD

Calendar/Event Events Same as ../me/calendar

Beta

DemoGroups REST API Requests

• Permissions• Uses existing Read or ReadWrite permission for Mail, Calendar, Contacts or Groups

• Supported entity collections• Messages• Events• Contacts• Groups (Unseen Count)

• Conversations• Threads• Events

• Samples• POST https://outlook.office365.com/api/beta/me/subscriptions • Group - subscription https://outlook.office365.com/api/beta/me/groups(

'mygroup@contoso.com')/subscriptions

Introducing – Webhooks (preview)

• Timezone support for events

• Full text search ($Search) messageshttps://outlook.office365.com/api/beta/me/folders/inbox/messages?$

search=foo

• Get User HD photo

• CORS support*Build Single Page Apps

Other notable new features

Demo

Search, Photo

Demo

Getting Started:Office 365 APIs starter Project – Visual Studio

• Provide instrumentation in your app• Add Header info like ‘user-agent’, ‘client-request-id’• Maintain a failure log for troubleshooting. • Include ‘client-request-id’ and all HTTP response headers from the

failed requests.

• Be mindful of requests that generate large responses

• Use $top, $select, $filter to narrow requests• App performance depends on it• Keep your app responsive by not getting throttled• Be conservative with refresh requests/frequent polling

Best Practices

I am confused: REST API, EWS or EAS? EWS EAS RESTFull Feature Set Limited Growing Oauth supportReach: Exchange OnlineHybrid with 2013 ComingOn Prem 2013 ComingOn Prem 2010 and 2007Outlook.com users*

Modern API:Easy Discovery and ExplorationMetadataEasy to learn and developDesigned for App developersLighter payloadGranular ConsentAPI Sandbox

Client SDKs.Net, Java

.Net, Android, iOS, JS (cordova)

Licensing

Enable end to end scenarios – web, mobile focus*

• Batching• Custom/Extended properties• Sync• Free busy• Mail tips, OOF settings• Delegate scenarios

*71% of work will be done by web based, mobile apps by 2020

Roadmap

Call to action

dev.office.com

Explore http://apisandbox.msdn.microsoft.com

Sign uphttp://dev.office.com/getting-started

Get trainedhttp://dev.office.com/training

In Review: Session Objectives And Takeaways• Session Objective(s):

• Why are the O365 REST APIs Important?• Drill down into the API’s• Best practices• Compare with existing API’s like EWS• Sneak-peak into what is coming

• Key Takeaway(s):• APIs that allows you to create end to end O365 apps with

targeted scopes

• Lightweight and quick to learn and develop

Related sessions

728 Integrating web applications for Office 365

Online Soon

630 Get Your Hands Dirty with the Office 365 APIs, Authentication and SDKs

641 Supercharging your custom solutions with the Office 365 unified API endpoint

676 Building Solutions with Office Graph

701 Deep Dive into the Office 365 Groups REST API

632 Office 365 and Azure: A Developer's Guide for Maximizing the Cloud

722 Mobile Development with iOS, Android and Office 365

715 Connecting to OneNote in the Cloud with Office 365 APIs

661 Building Multi-Device Applications with Xamarin with Office 365 APIs

689 Building a Single Page App Using Angular and Typescript Using Office 365 APIs 10:30 AM

767 Building Universal Apps with Connected Services 02:00 PM

http://dev.office.com/devprogram

Developer Program Launch

E-mail Newsletters

Free Developer Subscriptio

n

1 YEAR FREE

Free Training

Free Tools

Webinars

Call to action

Sign up for Developer Program

Collect your stickers at //build

Check out the express talks

© 2015 Microsoft Corporation. All rights reserved.