How conditional access policies apply to Microsoft Graph is changing. Applications need to be updated to handle scenarios where conditional access policies are configured. For more information and guidance, see Developer guidance for Microsoft Entra Conditional Access.
OData namespace
The Microsoft Graph API defines most of its resources, methods, and enumerations in the OData namespace, microsoft.graph, in the Microsoft Graph metadata. A small number of API sets are defined in their sub-namespaces, such as the call records API which defines resources like callRecord in microsoft.graph.callRecords.
Unless explicitly specified in the corresponding topic, assume types, methods, and enumerations are part of the microsoft.graph namespace.
Call a REST API method
To read from or write to a resource such as a user or an email message, you construct a request that looks like the following:
{HTTP method} - The HTTP method used on the request to Microsoft Graph.
{version} - The version of the Microsoft Graph API your application is using.
{resource} - The resource in Microsoft Graph that you're referencing.
{query-parameters} - Optional OData query options or REST method parameters that customize the response.
{headers} - Request headers that customize the request. Can be optional or required depending on the API.
After you make a request, a response is returned that includes:
Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
@odata.nextLink - If your request returns a lot of data, you need to page through it by using the URL returned in @odata.nextLink. For details, see Paging.
Response headers - Additional information about the response, such as the type of content returned and the request-id that you can use to correlate the response to the request.
HTTP methods
Microsoft Graph uses the HTTP method on your request to determine what your request is doing. Depending on the resource, the API may support operations including actions, functions, or CRUD operations described below.
Method
Description
GET
Read data from a resource.
POST
Create a new resource, or perform an action.
PATCH
Update a resource with new values, or upsert a resource (create if resource doesn't exist, update otherwise).
PUT
Replace a resource with a new one.
DELETE
Remove a resource.
For the CRUD methods GET and DELETE, no request body is required.
The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.
Important
Write requests in the Microsoft Graph API have a size limit of 4 MB.
In some cases, the actual write request size limit is lower than 4 MB. For example, attaching a file to a user event by POST /me/events/{id}/attachments has a request size limit of 3 MB, because a file around 3.5 MB can become larger than 4 MB when encoded in base64.
Requests exceeding the size limit fail with the status code HTTP 413, and the error message "Request entity too large" or "Payload too large".
Version
Microsoft Graph currently supports two versions: v1.0 and beta.
v1.0 includes generally available APIs. Use the v1.0 version for all production apps.
beta includes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.
A resource can be an entity or complex type, commonly defined with properties. Entities differ from complex types by always including an id property.
Your URL will include the resource you are interacting with in the request, such as me, user, group, drive, and site. Often, top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. You can also interact with resources using methods; for example, to send an email, use me/sendMail. For more information, see Access data and methods by navigating Microsoft Graph.
Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.
Query parameters can be OData system query options, or other strings that a method accepts to customize its response.
You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.
For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@contoso.com.
GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'
Aside from OData query options, some methods require parameter values specified as part of the query URL. For example, you can get a collection of events that occurred during a time period in a user's calendar, by querying the calendarView relationship of a user, and specifying the period startDateTime and endDateTime values as query parameters:
GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000
Headers
Microsoft Graph supports both HTTP standard headers and custom headers.
Specific APIs may require additional headers to be included in the request. On the other hand, Microsoft Graph will always return mandatory headers, such as the request-id header in the response, or some headers may be specific to some APIs or functionality, for example, the Retry-After header is included when your app hits throttling limits; or the Location header that's included for long-running operations.
Headers are case-insensitive as defined in rfc 9110 unless explicitly specified otherwise.
You can either access demo data without signing in, or you can sign in to a tenant of your own. Use the following steps to build the request:
Select the HTTP method.
Select the version of API that you want to use.
Type the query in the request text box.
Select Run Query.
The following example shows a request that returns information about users in the demo tenant:
Sample queries are provided in Graph Explorer to enable you to more quickly run common requests. To see the samples that are available, select show more samples. Select On for the set of samples that you want to see, and then after closing the selection window, you should see a list of predefined requests.
A status code and message are displayed after a request is sent and the response is shown in the Response Preview tab.
Postman
Postman is a tool that you can use to build and test requests using the Microsoft Graph APIs. You can download Postman at: https://www.getpostman.com/. To interact with Microsoft Graph in Postman, you use the Microsoft Graph collection.
Microsoft Graph provides access to data stored across Microsoft 365 services. Custom applications can use the Microsoft Graph API to connect to data and use it in custom applications to enhance organizational productivity.
Demonstrate understanding of Microsoft 365, to deliver industry-leading productivity apps along with intelligent cloud services, and world-class security.
Try Microsoft Graph APIs on the default sample tenant to explore capabilities, or sign in to your tenant and use it as a prototyping tool to fulfill your app scenarios.
In addition to using the Microsoft Graph API to read and write data, you can use a number of request patterns to traverse through the resources in Microsoft Graph. The metadata document also helps you to understand the data model of the resources and relationships in Microsoft Graph.
Learn about errors that can be returned in Microsoft Graph responses. Errors are returned using standard HTTP status codes and a JSON error response object.
Use Graph Explorer to make Microsoft Graph REST API requests and view corresponding responses. Learn how to use some of the important features in Graph Explorer.