Microsoft Graph API API Essential Guide

What type of API does Microsoft Graph API provide?

Microsoft Graph API uses a REST API architecture. It uses standard HTTP methods like GET, POST, PATCH, DELETE for operations. It has resource-based URLs for accessing different entities and data. Responses are typically returned in JSON format. It supports OData query parameters for filtering, sorting, and pagination. Authentication is done via OAuth 2.0. It provides a unified endpoint (https://graph.microsoft.com) to access various Microsoft 365 services.

Some key advantages of Microsoft Graph API being RESTful include simplicity and ease of use, scalability, statelessness, cacheability, and uniform interface.

In summary, Microsoft Graph API follows REST architectural principles, making it a RESTful API rather than using SOAP or GraphQL approaches. This aligns with modern API design practices and provides developers with a familiar and flexible way to interact with Microsoft 365 services.

Does the Microsoft Graph API API have webhooks?

Yes, the official Microsoft Graph API does have webhooks, and you can subscribe to various types of events. Here are the key points about Microsoft Graph API webhooks and event subscriptions:

Webhook Support

Microsoft Graph API supports webhooks for receiving change notifications. Webhooks allow you to set up an HTTP-based callback API in your infrastructure to receive notifications about changes in Microsoft Graph resources.

Event Types and Resources

You can subscribe to various types of events for different resources in Microsoft Graph. Here are some examples:

1. Change types:

   • Created
   • Updated
   • Deleted

2. Resources you can subscribe to:

   • Microsoft Entra ID: User, Group
   • Microsoft Outlook: Event (calendar meeting), Message (email), Contact
   • Microsoft Teams: ChatMessage, CallRecord (meeting)
   • OneDrive: DriveItem
   • Microsoft SharePoint: List
   • To Do: To Do Task
   • Security alerts: Alert
   • Cloud printing: Printer, Print Task Definition
   • Microsoft Conversations: Conversation

Subscription Process

To subscribe to events, you need to:

1. Create a publicly accessible, HTTPS-secured endpoint that will receive the notifications.
2. Send a POST request to the /subscriptions endpoint to create a subscription.
3. Specify the following in your subscription request:
   • changeType: The types of changes you want to receive (e.g., "updated,deleted,created")
   • notificationUrl: The URL of your webhook endpoint
   • resource: The resource you want to monitor (e.g., "users")
   • expirationDateTime: When the subscription should expire
   • Other optional properties like clientState for verification

Considerations

1. Your webhook endpoint must be publicly accessible and HTTPS-secured.
2. Microsoft Graph validates the notificationUrl before completing the subscription creation.
3. You need to regularly renew subscriptions to maintain their validity.
4. Your endpoint must provide timely and consistent HTTP responses to reliably receive notifications.

Best Practices

1. Properly decode the validation token sent by Microsoft Graph during subscription creation.
2. Escape any HTML or JavaScript in the validation token to prevent cross-site scripting attacks.
3. Treat the validation token as opaque, as its format may change without notice.

In summary, Microsoft Graph API offers robust webhook support for various resources and event types, allowing developers to receive real-time notifications about changes in Microsoft 365 and Azure services.

Rate Limits and other limitations

Here are the key points about API rate limits for the Microsoft Graph API:

General Limits

• There is a global limit of 130,000 requests per 10 seconds per app across all tenants.

• Individual services within Microsoft Graph (e.g. Outlook, Microsoft Teams, etc.) have their own specific throttling limits.

Service-Specific Limits

Some examples of service-specific limits include:

• Microsoft Teams: 30 requests per second (rps) per app, 300 rps per tenant
• Outlook: 10,000 requests in a 10-minute period for v1.0 and beta endpoints
• OneNote: 120 requests per minute and 400 per hour in delegated context
• Identity and access reports: 5 requests per 10 seconds per app per tenant

Throttling Behavior

• When throttling occurs, Microsoft Graph returns HTTP status code 429 (Too Many Requests).
• A suggested wait time is returned in the response header of failed requests.
• Throttling can depend on the type and number of requests - for example, writes may be throttled while reads are still permitted.

Best Practices

• Implement error handling for 429 responses and use exponential backoff when retrying.
• Use filters and select only needed data to reduce response sizes.
• For high volume data extraction, consider using Microsoft Graph Data Connect instead of REST APIs.
• The exact limits are not always disclosed and can change, so implementing proper error handling is crucial.

In summary, while there are some documented limits, the exact throttling thresholds can vary. Implementing proper error handling and backoff logic is essential when working with the Microsoft Graph API at scale.

Latest API Version

The most recent version of the Microsoft Graph API is v1.0. Here are the key details:

Current Version

• The current version of Microsoft Graph API is v1.0
• It is accessible at the endpoint: https://graph.microsoft.com/v1.0
• This version contains features that are generally available and ready for production use

Beta Version

• There is also a beta version available at: https://graph.microsoft.com/beta
• The beta version contains APIs that are still in preview and may change
• Use of beta APIs in production applications is not supported

Key Points

• Microsoft Graph provides a unified programmability model to access data in Microsoft 365, Windows, and Enterprise Mobility + Security
• The v1.0 endpoint has gone through rigorous review and feedback to meet production needs
• Updates to v1.0 APIs are additive and don't break existing app scenarios
• Microsoft regularly evaluates customer needs and releases new features to both beta and v1.0 endpoints

Best Practices

• Use the v1.0 endpoint for production applications
• Refer to the Microsoft Graph API changelog for details on API-level updates
• Don't take production dependencies on beta APIs, as they can change without notice
• Consider joining the Microsoft 365 platform community calls to stay updated on new features

In summary, v1.0 is the current stable version for production use, while the beta endpoint allows developers to test upcoming features. Always use v1.0 for production applications and keep an eye on the changelog for updates.

How to get a Microsoft Graph API developer account and API Keys?

To get a developer account for Microsoft Graph API and create an API integration, you need to follow these steps:

1. Set up a Microsoft 365 developer account

• If you don't already have one, sign up for a Microsoft 365 developer account. You may qualify for one through the Microsoft 365 Developer Program.
• Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

2. Register an application in Microsoft Entra ID (formerly Azure AD)

• Sign in to the Azure portal with your Microsoft 365 developer account.
• Navigate to Microsoft Entra ID > App registrations > New registration.
• Provide a name for your application and select the appropriate supported account types.
• For the redirect URI, you can use https://login.microsoftonline.com/common/oauth2/nativeclient for now.

3. Configure API permissions

• In your newly registered app, go to API permissions.
• Click "Add a permission" and select "Microsoft Graph".
• Choose the permissions your app needs. For example:
  • For delegated permissions, you might select Mail.Read.
  • For application permissions, you might select User.Read.All.
• After adding permissions, click "Grant admin consent" if required.

4. Get the necessary credentials

• From the Overview page of your app registration, note down the following:
  • Application (client) ID
  • Directory (tenant) ID
• Create a new client secret:
  • Go to Certificates & secrets > New client secret
  • Provide a description and select an expiration period
  • Copy the generated secret value immediately (you won't be able to see it again)

5. Implement authentication in your application

• Use the Microsoft Authentication Library (MSAL) or another OAuth 2.0 library to implement the authentication flow in your application.
• You'll need to use the client ID, tenant ID, and client secret obtained in the previous step.

What can you do with the Microsoft Graph API API?

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

Microsoft 365 core services

• Bookings

  • Manage appointment scheduling and customer information

• Calendar

  • Access and manage calendar events and schedules

• Delve

  • Retrieve insights and trending content

• Excel

  • Interact with Excel spreadsheets and data

• Microsoft 365 compliance eDiscovery

  • Manage eDiscovery cases and data

• Microsoft Search

  • Access and manage search functionality

• OneDrive

  • Interact with files and folders stored in OneDrive

• OneNote

  • Access and manage OneNote notebooks and content

• Outlook/Exchange

  • Manage emails, contacts, and other Outlook data

• People (Outlook contacts)

  • Access and manage contact information

• Planner

  • Manage tasks and plans

• SharePoint

  • Interact with SharePoint sites, lists, and documents

• Teams

  • Manage teams, channels, and chat functionality

• To Do

  • Manage tasks and to-do lists

• Viva Insights

  • Access workplace analytics and insights

Enterprise Mobility + Security services

• Advanced Threat Analytics

  • Access threat detection data

• Advanced Threat Protection

  • Manage advanced security features

• Microsoft Entra ID

  • Manage user identities and access control

• Identity Manager

  • Manage identity lifecycle and access

• Intune

  • Manage mobile devices and applications

Windows services

• Activities

  • Access user activities across devices

• Devices

  • Manage and monitor Windows devices

• Notifications

  • Send and manage notifications

• Universal Print

  • Manage printing services

Dynamics 365 Business Central services

• Access and manage business data from Dynamics 365 Business Central

Additional capabilities

• Profile API (preview)

  • Model and represent people in Microsoft 365 services

• People API

  • Access relevant people for a user, ordered by relevance

• Insights API

  • Access relevant documents and files for a user

• Analytics API (preview)

  • Access advanced analytics and machine learning insights

Key points to consider

1. Microsoft Graph API provides a unified endpoint (https://graph.microsoft.com) for accessing various Microsoft 365 services.

2. You can use REST APIs or SDKs to interact with the Microsoft Graph API.

3. The API supports various scenarios including productivity, collaboration, education, and workplace intelligence.

4. Microsoft Graph Data Connect can be used for accessing data at scale and building intelligent applications.

5. Microsoft Graph connectors allow bringing external data into Microsoft Graph services.

6. The API is available in two versions: v1.0 (for production) and beta (for testing).

7. Most resources are defined in the microsoft.graph namespace, with some exceptions in subnamespaces.

8. Graph Explorer is a web-based tool for building and testing Microsoft Graph API requests.