Introduction To MS Graph Explorer

Nilesh Shah
Apr 25, 2017
7k
0
0
Article

First, let’s start with a quick introduction of MS Graph.

What is MS Graph?

The official MS documentation defines MS Graph as,

“Microsoft Graph exposes multiple APIs from Office 365 and other Microsoft cloud services through a single endpoint, https://graph.microsoft.com. Microsoft Graph simplifies queries that would otherwise be more complex.”

So, in a nutshell, MS Graph gives you a single REST API endpoint which you can call to interact with “almost anything” in Office365. It delegates calls to different Office 365 cloud services via one single endpoint.

Now, let’s learn about MS Graph Explorer.

What MS Graph Explorer is

MS Graph Explorer is a fantastic tool if you want to work with MS Graph APIs or if you are learning to develop with Graph APIs. Consider it as a developer sandbox or a playground where a developer can have firsthand experience of MS Graph APIs.

What you need to work with MS Graph Explorer

MS Graph Explorer provides you default login – a demo tenant with which you can fire some GET calls using MS Graph APIs. But, if you want to explore more and want to also fire POST, PATCH and DELETE calls to MS Graph API, then you will need an Office365 account.

Warning

A word of caution here; never play with your live Office365 data or work account here with MS Graph APIs. You may accidently update or delete some important information. It is advisable to use a test/demo account.

If you join the MS Office 365 developer program here, Microsoft will give you one year free Office 365 developer subscription for non-commercial use with 5 users. You can read more about it in my related article “Office 365 developer program”.

What you can do with MS Graph Explorer

A lot!

MS Graph Explorer gives you a test client to access whatever you can access with MS Graph REST APIs. Using MS Graph Explorer, you can,

Access/Modify data from Office 365 and other cloud services like SharePoint online, OneDrive, etc.
Navigate different Office 365 entities and traverse the relationships amongst them
Get intelligence and insights from the Microsoft cloud (limited to commercial users only)

In short, MS Graph Explorer is a one stop shop for everything you want to play with, in Graph APIs.

Why you should use MS Graph Explorer

MS Graph Explorer is a great tool to test how MS Graph APIs work. A developer can use MS Graph Explorer to:

Test Graph API calling logic beforehand dealing with any endpoint.
See what data Graph API gives you back.
See how the POST, PATCH and DELETE calls work.
See how an entity in Office 365 can be accessed, using which relationship path.

The first look of MS Graph Explorer

The screenshot of MS Graph Explorer with some annotations above is mostly self-explanatory. API version and Request type selections are covered in below sections. I would like to cover some parts which were not mentioned above.

The “History” button

It maintains the history of the API calls you made to the Graph API, and clicking on the history, you can easily go back to that call. Remember, as you make the Graph API calls, the browser URL does not change, so to get back to any of your previous calls, you need to click this button.

When you click on the “History” button, you will see a section as shown below. You can click on any URL request and it will be re-played.

“Request Header” and “Request Body” section

Along with the API endpoint and passing parameters in query string, sometimes you will also need to pass more data to the Graph API.

The HTTP request headers can be specified in the “Request Header” area. Once you click on the “REQUEST HEADER” link, a text area will appear below it,

Similarly, the HTTP Request body can be specified in the area which appears once you click on the “REQUEST BODY” link as shown below. But remember you need to be logged in to enable the link, if you are using demo tenant then the link will be disabled,

Also, in the case of “POST” and “PATCH” verbs selection only, the request body link will be enabled, otherwise it will be disabled. Once you click on the enabled “REQUEST BODY” link, then a text area below it will appear,

Now, go to the service endpoint address bar and type the following URL:

https://graph.microsoft.com/v1.0/organization/users

You will see the MS Graph Explorer that will show you a link “INSERT USERS TEMPLATE”.

When you click on the “INSERT USERS TEMPLATE” link, MS Graph Explorer will insert JSON for creating a user.

Do you see now how much MS Graph Explorer makes it easier for you to play with the API calls?

You can change some data from the default text and then hit the “GO” button for the user to be created in your organization’s Office 365 account. Remember to use a test/demo account and not the live account.

If you really pressed the “GO” button, then the Graph Explorer will show you the result in the “RESPONSE” section.

How to fire actual API calls is covered in the section “Let’s try it out” below.

API versions supported by MS Graph Explorer

As of now, MS Graph APIs are only in two versions: V1.0 for general availability, and “beta” for preview. MS Graph Explorer supports both these versions.

You can see the supported API versions in MS Graph Explorer when you expand the “API Version” selection, as shown below.

HTTP request types/verbs/actions that are supported in MS Graph Explorer

MS Graph Explorer supports the following HTTP actions/HTTP verbs.

Let’s try it out

Below, I will explain how some calls to MS Graph API can be made using the Graph Explorer.

Calls with demo tenant

The following calls can be executed using the demo tenant.

To get the currently logged in user, type the following in the address bar.

https://graph.microsoft.com/v1.0/me

Also notice, as you type in the address bar, the Graph Explorer will show you the possible endpoints (just like intelliSense).

Click on the “GO” button and you will see the result in the “RESPONSE” area.

Now, type https://graph.microsoft.com/v1.0/organization in the address bar and press “GO” button. You will see the logged in user’s organization info.
The following call will return the files stored in user’s OneDrive account.

Try some more “GET” calls on your own using the Graph Explorer. The list of more such calls can be found here.

Calls with your Office 365 account

The following calls will require you to login with an Office 365 account. Remember to use demo/test account and not the live account, because it may result in some live data loss.

Click on the “SIGN IN” link and login with your Office 365 test account.

To add a new user to your organization, type the following endpoint and make the request type as “POST”

https://graph.microsoft.com/v1.0/users

Click on the “INSERT USERS TEMPLATE” link inside “REQUEST BODY” area. Once MS Graph Explorer populates some default JSON data, change it as you like and click on the “GO” button.

Hopefully, a new user will be created in Office 365 and Graph API will respond with HTTP Status Code 201, meaning user is created.

Note the id of the user which can be used in subsequent calls to edit/delete the record.

Let’s now try to update the user’s value e.g. surname. Let’s update the value from current “Darrow” in above screenshot to “Sharp”.
Copy the JSON value from the response area (i.e. values inside and including the curly brackets).
Remove everything else but surname field, change the surname value to “Sharp”.
Change the request type to “PATCH”.
Change the API endpoint to include the above created user
- https://graph.microsoft.com/v1.0/users/6182c1b5-5f08-4d76-a164-9e0fe9b6688a
Click on the “GO” button.

Graph API will process the request and update the user’s last name to “Sharp”. It will respond with the HTTP Status Code 204.

Change the request type to “GET” and fire the same call again, you will see the last name is changed to “Sharp” now.

Now, let’s fire a delete call and delete the above generated user. Use caution here not to delete any of your live users!

Change the request type to “DELETE”, keep the API endpoint same as last call and click on “GO”

You will see that Graph API responds with HTTP Status Code 204 again. The user is deleted from Office 365.

You can make sure the user is deleted by firing a GET on all users,

Check the response JSON, above user will not be in the response.

What’s next

After reading this introduction to MS Graph Explorer, I think you must be interested to know more about MS Graph API. Wait for my next article on MS Graph API, and until it is published you can go to internet and,