Microsoft Office 365 API Essential Guide

What type of API does Microsoft Office 365 provide?

Microsoft Office 365 primarily uses a REST API called Microsoft Graph. The main API for Office 365 is Microsoft Graph, which is a REST API.

Microsoft Graph provides a unified programmability model that you can use to access data in Microsoft 365, Windows 10, and Enterprise Mobility + Security.

While the primary API is REST-based, Microsoft also offers GraphQL capabilities for some scenarios:

• Azure API Management allows you to create a GraphQL facade over existing REST APIs, including those from Office 365.
• This feature, called "Synthetic GraphQL", enables you to build a GraphQL service from a set of REST APIs.

The older SOAP-based APIs for Exchange Web Services (EWS) are still available but are being phased out in favor of Microsoft Graph.

Microsoft Graph provides a single endpoint (https://graph.microsoft.com) to access various Office 365 services, including:

• Outlook/Exchange (mail, calendars, contacts)
• OneDrive/SharePoint (files)
• Teams
• And many other Microsoft 365 services

Authentication for Microsoft Graph is handled through Azure Active Directory (Azure AD) using OAuth 2.0 tokens.

In summary, while Microsoft Office 365 primarily uses a REST API (Microsoft Graph), there are options to work with GraphQL through Azure API Management. The older SOAP APIs are still available but are being deprecated in favor of the more modern REST-based Microsoft Graph API.

Does the Microsoft Office 365 API have webhooks?

The official Microsoft Office 365 API supports webhooks, with some considerations:

Availability of Webhooks

• Available in the Government Community Cloud (GCC) environment
• Not available in GCC-High and Department of Defense (DOD) environments
• In GCC-High, only the Incoming Webhook connector type is available, requiring manual upload by tenant admins

Types of Events for Subscription

The Office 365 Management Activity API allows subscription to:

1. Audit.AzureActiveDirectory
2. Audit.Exchange
3. Audit.SharePoint
4. Audit.General (all other workloads)
5. DLP.All (DLP events for all workloads)

Key Considerations

• Webhooks enable integration of Office 365 data with custom code on external services
• Consider scalability, synchronous/asynchronous capabilities, and ease of consumption when choosing between webhooks and Azure Service Bus integration
• Webhooks can be invoked from plugins or custom workflow activities
• Authentication options: HttpHeader, WebhookKey, and HttpQueryString
• Limitations on subscriptions per app and per tenant may affect large-scale implementations

Best Practices

1. Test webhook registration using a request logging site before implementation
2. Implement proper authentication for the webhook endpoint
3. Be aware of subscription expiration and implement a renewal process
4. Consider latency between event occurrence and availability in content blobs
5. Enable unified audit logging for the Office 365 organization before accessing API data

Rate Limits and other limitations

Here are the key API rate limits for Microsoft Office 365 API and related services:

General Microsoft Graph Limits

• 130,000 requests per 10 seconds per app across all tenants

Outlook Service Limits

• 10,000 API requests in a 10 minute period per mailbox
• 4 concurrent requests per mailbox
• 150 MB upload in a 5-minute period per mailbox

Microsoft Teams Limits

• 30 requests per second per app
• 300 requests per second per tenant
• 1 request per second per user for certain operations

OneNote Service Limits

• 120 requests per 1 minute and 400 per 1 hour per app per user (delegated context)
• 240 requests per 1 minute and 800 per 1 hour per app (app-only context)
• 5 concurrent requests (delegated context)
• 20 concurrent requests (app-only context)

Microsoft 365 Reports Service Limits

• 14 requests per 10 minutes per app per tenant (CSV)
• 40 requests per 10 minutes per tenant for all apps (CSV)
• 100 requests per 10 minutes per app per tenant (JSON beta)

Identity and Access Reports Limits

• 5 requests per 10 seconds per app per tenant

Excel Service Limits

• 5000 requests per 10 seconds per app across all tenants
• 1500 requests per 10 seconds per app per tenant

Key Points to Consider

• Different services have their own specific limits that apply in addition to the general Graph limits.
• Limits are often evaluated over sliding time windows (e.g. 10 minutes, 1 hour).
• Some limits apply per app, per tenant, per user, or combinations of these.
• Exceeding limits typically results in 429 Too Many Requests errors.
• Proper error handling and retries are important when working with these APIs.

Best Practices

• Use efficient querying and filtering to reduce the number of API calls needed.
• Implement proper throttling handling and backoff when limits are reached.
• Batch requests where possible to reduce total number of calls.
• Monitor your usage to stay well below the limits during normal operation.
• Consider using change notifications instead of frequent polling where applicable.

By understanding and working within these limits, you can build robust applications that integrate effectively with Microsoft 365 services via the Graph API.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Microsoft Office 365 API:

Current Status of Office 365 APIs

1. The Office 365 Management APIs provide a single extensibility platform for Office 365 management tasks, including service communications, security, compliance, reporting, and auditing.

2. The Office 365 Management APIs are consistent in design and implementation with the current suite of Office 365 REST APIs, using common industry-standard approaches, including OAuth v2, OData v4, and JSON.

3. Applications for these APIs are registered in Microsoft Entra ID, providing a consistent way to authenticate and authorize apps.

Recent Developments

1. Microsoft recently announced new Microsoft Defender for Office 365 APIs for retrieving threat data and remediating emails (announced on July 31, 2024).

2. These new APIs extend the existing Microsoft Graph API functionality with additional key benefits, such as:

   • Integration with security tools and services like SOAR platforms
   • Retrieval of detailed threat information
   • Ability to perform response actions on emails within security tools and automation platforms

3. The new APIs are built around least-privilege with their own permission scopes and include auditing capabilities.

API Documentation

1. Detailed documentation and example code for these APIs are available in the Graph Reference Guide.

2. The APIs include functionality to:

   • Search for emails with specific criteria
   • Get detailed threat information on individual email messages
   • Perform remediation activities on emails (e.g., soft delete, hard delete, move to inbox, etc.)

Important Note

While these are recent developments, it's important to note that Microsoft is continually updating and improving its APIs. For the most up-to-date information, it's recommended to check the official Microsoft documentation or developer resources.

How to get a Microsoft Office 365 developer account and API Keys?

Sign up for a Microsoft 365 Developer Program account

1. Go to the Microsoft 365 Developer Program website and sign up for a free account.

2. This program provides you with a Microsoft 365 E5 developer subscription, which includes access to Office 365 APIs.

3. The subscription is free for 90 days and can be renewed as long as you're actively developing.

Register your application in Microsoft Entra ID

1. Sign in to the Azure portal using your Microsoft 365 Developer Program credentials.

2. In the left navigation pane, select "Microsoft Entra ID".

3. Select "App registrations" and then "New registration".

4. On the registration page:

   • Name your app
   • Choose who can use the app and access the API
   • Provide a redirect URL if needed

5. After registering, you'll receive a Client ID, which is important for API authentication.

Configure application permissions

1. In the Azure Portal, go to your registered app and select "API Permissions".

2. Click "Add a permission" and select "Office 365 Management APIs".

3. Choose the required permissions for your app (Delegated and/or Application permissions).

4. Grant admin consent for the permissions.

Get tenant admin consent

1. Construct a special URL for tenant admin consent.

2. Have the tenant admin sign in using this URL to grant permissions to your app.

Build your app

1. Implement the consent experience in your app.

2. Store the tenant ID securely.

3. Manage access tokens for API calls.

4. Implement necessary components like webhook listeners and data retrieval/storage.

What can you do with the Microsoft Office 365 API?

Based on the provided search results, here's a list of data models you can interact with using the Microsoft Office 365 API, along with what is possible for each:

Microsoft 365 Reporting API Data Tables

• Tenant Product Usage

  • Contains monthly totals of enabled, active users, month-over-month retained users, first-time users, and cumulative active users
  • Provides data for a rolling 12-month period including the current partial month

• Tenant Product Activity

  • Contains monthly totals of activities and active user count for various activities within products
  • Provides data for a rolling 12-month period including the current partial month

• Tenant Office Licenses

  • Contains data about the number of Microsoft Office subscriptions assigned to users
  • Provides end-of-month state data for a rolling 12-month period

• Tenant Mailbox Usage

  • Contains data about user mailboxes, including total mailbox count and storage usage
  • Provides end-of-month state data for a rolling 12-month period

• Tenant Client Usage

  • Contains data about users actively using specific clients/devices to connect to Exchange Online, Skype for Business, and Viva Engage
  • Provides monthly aggregated data for a rolling 12-month period

• Tenant SharePoint Online Usage

  • Contains data about SharePoint sites, including total number of sites, document count, file count by activity type, and storage used
  • Provides end-of-month state data for a rolling 12-month period

• Tenant OneDrive for Business Usage

  • Contains data about OneDrive accounts, including number of accounts, document count, storage used, and file count by activity type
  • Provides end-of-month state data for a rolling 12-month period

• Tenant Microsoft 365 Groups Usage

  • Contains data about Microsoft 365 Groups usage, including Mailbox, SharePoint, and Viva Engage
  • Provides end-of-month state data for a rolling 12-month period

• Tenant Office Activation

  • Contains data about Office subscription activations, including count per device type and service plan
  • Provides end-of-month state data for a rolling 12-month period

• User State

  • Contains metadata about users, including display name, assigned products, location, department, title, and company
  • Provides data for users with assigned licenses during the last complete month

• User Activity

  • Contains per-user level information about activity performed by licensed users
  • Provides data for users who performed an activity in any service during the last complete month

Office 365 Management Activity API Schemas

• Common schema: Core Office 365 auditing concepts and dimensions
• Copilot schema: Events related to Copilot interactions
• SharePoint schemas: Various schemas for SharePoint-related activities
• Exchange schemas: Schemas for Exchange admin and mailbox audit data
• Microsoft Entra ID schemas: Schemas for Microsoft Entra audit data and logon events
• DLP schema: Data Loss Prevention events
• Security and Compliance schemas: Events and alerts related to security and compliance
• Yammer schema: Yammer events
• Data Center Security schemas: Data center security audit data
• Microsoft Teams schema: Microsoft Teams events
• Microsoft Defender for Office 365 schema: Defender for Office 365 and threat investigation data
• Power BI schema: Power BI events
• Dynamics 365 schema: Dynamics 365 events
• Microsoft Forms schema: Microsoft Forms events
• Viva Goals schema: Viva Goals events
• Microsoft Planner schema: Microsoft Planner events
• Microsoft Project for the web schema: Microsoft Project for the web events

Microsoft Graph API

• Provides access to data from various Microsoft 365 core services, including:
  • Bookings, Calendar, Delve, Excel, OneDrive, OneNote, Outlook/Exchange, People, Planner, SharePoint, Teams, To Do, and Viva Insights
• Offers access to Enterprise Mobility + Security services data
• Includes Windows services data (activities, devices, notifications, Universal Print)
• Provides access to Dynamics 365 Business Central services data

These data models allow developers to interact with a wide range of Microsoft 365 data, enabling the creation of custom applications, reports, and integrations that leverage the rich ecosystem of Microsoft's cloud services.