What is the Microsoft Graph API?

A basic question, what is Microsoft Graph API?

Microsoft Graph is a REST API built on the OData protocol.

So… what does that mean?

An API is an Application Programming Interface. Put simply, it is a set of tools that can be used to communicate with an application. Most common APIs are text based and used to access back-end services.
A REST API is a web service that allows a client (the requestor) to access resources on an endpoint (the server). REST stands for Representational State Transfer. RESTful services allow requestors to interact with textual resources using a predefined set of operators. REST servers are stateless, which means no client context is stored on the server. The requests themselves supply all the relevant client information in the request.
OData stands for Open Data Protocol. It is a standard that defines the best practices for building and interacting with REST APIs. APIs that are built on OData have common structures that make it easier to explore the underlying data.

That’s starting to make sense, but how does that apply to me?

By understanding the basics of how REST APIs are built we can begin to put them into use in our environment. All REST APIs use standard elements when making calls:

The Endpoint (URL) is the location where the web service is listening for a request.
The Method is a verb that describes the type of request being made. Common methods include:
- GET – returns a resource
- POST – creates a resource
- PUT – updates a resource by replacing all its properties
- PATCH – updates a resource by changing a single property
- DELETE – removes a resource
Headers include information about the requestor, including client information and the authentication token.
The Body includes a payload with information about the request. It is not always required. When accessing Graph, the body will usually be delivered in a JSON payload.

Breaking down a basic request

Now that we you understand the basics of Microsoft Graph, let’s break down a couple simple requests

There are a lot of different ways to access Microsoft Graph. For this post we will use Graph Explorer. Graph Explorer is Microsoft tool that lets you make API calls to Microsoft Graph and see the response.

There are other features available that make Graph Explorer an important tool for understanding Microsoft Graph, but those will be covered more in depth in a later posts.

In our first example we will use the Graph Explorer to return information about our user object from Azure Active Directory.

1️⃣ Open the Graph Explorer by going to https://aka.ms/ge in a browser. In the upper left corner click on Sign into Graph Explorer button. If you don’t sign in you can make test calls to a sample account, but by signing in you will be able to make calls against your own tenant.

Note Note: Click on the images to view at the full size.

2️⃣ Sign into Graph Explorer with your username and password.

3️⃣ If your organization has never consented to using Graph Explorer, you may be prompted to consent to allow the application to access your profile information. If you are signed in as an administrator, you can consent for your entire organization. For this example, we will click Accept.

4️⃣ Graph Explorer has been pre-populated with a basic API call. The first option is the method dropdown box. In this case we are making a GET call. The second box is the Microsoft Graph version. There are two versions of Microsoft Graph that we can access, v1.0 and beta. You can use either version, but remember the beta endpoint is subject to changes. Finally, we have an address bar where we can enter the URL for the endpoint we would like to access.

5️⃣ The default endpoint for this query is https://graph.microsoft.com/v1.0/me. This query returns the querying user’s Entra ID user object. In this example we returned the logged in user’s user object:

In the upper left corner, the response status is displayed. This request took 1300 ms, and returned a status of 200, which means it was successful.

6️⃣ On the left side of Graph Explorer, we see several sample queries. Scroll down to users, expand it, and select “Patch me.” We will use this sample to make another API call to PATCH our user object.

The GET request above didn’t include a body. Requests that will create or update objects will require information about the update to be made. In this case when we selected the sample query it changed the selected method to “PATCH,” and filled in the body with a JSON payload. For this example we will update the user’s department. The endpoint is still pointing at https://graph.microsoft.com/v1.0/me because we are updating the logged in user’s AD User object.

7️⃣ If we click on the “Request headers” tab, we can see that this request includes the content type in the headers. This tells the service the type of payload that is being included in the request. Here we see that our content type is application/json.

8️⃣ Finally, we can click on the Access token to see the token that is being passed. Each request passes an access token to the service with information about the requestor and their permissions. The token has a limited lifetime, but we can use it in other services to make requests until it expires. We can also view the contents of the token by clicking on the bracket icon {}. I will discuss the token more in depth in a later post.

If you get the error Forbidden 403. It means you need to click on the Modify permission tab then consent more permission for this call.

For instance, we need to consent the User.ReadWrite.All permission to the app.

9️⃣ After clicking on the Run query button, we receive a response that says, No content with a status of 204. This looks like it was successful, but since there was no content returned, we need to return the user object to see if the department changed.

🔟 When we run the original query above no department was returned. By default, not all properties are returned. Query options can be added to the end of the URL to change the information that is returned. Returned properties can be changed by using a select query option. Changing the selected properties can be done by appending ?$select=property1.property2,property3 to the end of the original query.

https://graph.microsoft.com/v1.0/me?$select=department,displayName,userPrincipalName

Here we can see that we received the response “OK” with a status code of 200. The response includes the properties that we included in our select query above. We can also see that the department was successfully updated.

This blog post was intended to be an entry point for using Microsoft Graph.

5/5 - (1 vote)