Microsoft Graph Mailbag – Explore Microsoft Graph with Postman
In today’s Microsoft Graph Mailbag post, we’ll take a look at the Microsoft Graph Postman collection.
Please be sure to follow this blog series using https://aka.ms/MSGraphMailbag or with RSS using https://developer.microsoft.com/graph/blogs/feed/?tag=MSGraphMailbag.
Introduction
The Microsoft Graph Postman collection is a curated set of API requests that you can use to experiment with and explore the Microsoft Graph API. It serves a similar purpose as the Graph Explorer, with a few notable differences. With the Postman collection, you can save custom requests and make requests with an app-only token.
Getting started
Instructions on forking and configuring the collection are found in Use Postman with the Microsoft Graph API. Jeremy Thake has posted a short YouTube video on getting started. I’ll summarize the process here.
Fork the collection
Forking the collection is necessary to get your own copy of the collection that you can modify. Once you’ve forked the collection into your personal workspace, you can use it in your browser or using the Postman desktop application.
Configure authentication
Postman has support for OAuth2 built in. The requests in our collection have been pre-configured to use the appropriate OAuth2 flows. Requests in the Delegated folder use the authentication code flow to authenticate as a user. Requests in the Application folder use the client credentials flow to authenticate as an application. Keep in mind that in order to use the requests in the Application folder, you will need an administrator to consent to the application permissions.
As you explore the requests in the collection, you’ll need to add additional permissions to your application registration and request a new token. For example, if you followed along with the instructions in our documentation, your application registration currently has User.Read and Mail.Read delegated permissions, and User.Read.All application permissions. That means the Get my messages request will succeed, but the Get my calendars request will fail with 403 Forbidden. To complete the request successfully, add Calendars.Read to the API permissions on the application registration, grant admin consent, and get a new token in Postman.
Add a request
Once you’ve explored the requests included in the collection, you may want to add additional requests. For example, there are no request for the personal contacts APIs. Let’s walk through the process of adding a request to list the authenticated user’s contacts.
First, add a Personal contacts folder in the Delegated folder. Select the ellipsis (…) on the Delegated folder to open the action menu, and select Add Folder. Be sure to leave the Type field set to Inherit auth from parent.
Add a request to the Personal contacts folder named Get my contacts. Using the information from the list contacts API reference page, we can fill in the request.
- The HTTP method is GET, so leave the method dropdown set to GET.
- The relative API url is
/me/contacts, so the full request URL ishttps://graph.microsoft.com/v1.0/me/contacts.
Finally, update your application registration to add the required permissions for the API. According to the API reference page, the least-privileged permission requires is Contacts.Read. Add the permission to your application registration’s delegated permissions. Once completed be sure to get a new access token by selecting the Delegated folder then selecting the Get New Access Token button on the Authorization tab. Select the Use Token button to select the new token.
You can now return to your Get my contacts request and select Send. The response lists the user’s contacts. Select Save to save the request to your fork of the collection.
Contribute to the collection
The number of available APIs on Microsoft Graph is way more than the currently included requests, and new APIs are added frequently. To be frank – we need help covering all of the available APIs! If you’ve created new requests that you’d like to share with the rest of the Microsoft Graph developer community, we strongly urge you to submit a pull request. You can also keep your forked copy up-to-date by pulling updates.
Conclusion
In this post, we learned how to fork the Microsoft Graph Postman collection and how to add new requests. With this you can experiment with the API and share your requests with the rest of the community. Until next time!
Today’s post was written by Jason Johnston, Principal Content Developer at Microsoft. You can follow Jason on Twitter @JasonJohMSFT. Join us for our next post July 13, 2021.
Light
Dark