Development API

Using Postman with the Brightspace API

Originally published February 20, 2019

Note that Postman is a third-party development tool. D2L recommends that you assess Postman's fit within your organization prior to using it.

D2L and Integration Standards

At D2L we have and will continue to be strong supporters of integration standards. In late 2016 we added OAuth 2.0 support for development of Brightspace API apps. OAuth 2.0 is an open standard authentication framework that provides multiple authentication flows, including the three-legged OAuth flow. It allows developers to write applications that access different services on behalf of a user.

Note that we will continue to support our Id/Key Pair authentication model, but our focus is going to be towards continued support and growth of OAuth 2.0. An example of this is a recent update that we made to our OAuth 2.0 implementation. In our March 2019 product release, we added support for using the Client_ID request parameter to identify itself when sending requests to the token endpoint. We are hopeful that this update will be of benefit to many Brightspace developers.

Why did we perform this update?

The inclusion of the Client_ID value will not impact any existing OAuth 2.0 apps. Other than being more adherent to the standard, through the Developer Community we heard from our customers that our OAuth 2.0 implementation was not compatible with some third-party API tools. More specifically, Brightspace developers were unable to use Postman with the Brightspace API as it included the Client_ID value in the request to perform an OAuth 2.0-based interaction.

What is Postman?

Postman is the market-leading API test tool. It is available to download at www.getpostman.com.

Postman is both powerful and easy to use and its Support Center is very helpful. Among its many features, we believe the following will be very helpful to Brightspace API developers:

Create development environments (e.g. one for your Brightspace test site and one for your production site)
Create environment variables (e.g. Brightspace Domain, API Version)
Create collections that provide the ability to run multiple API calls in sequence
Use JavaScript to pass variables into an API call
Use JavaScript to store variables after an API call

Start with a Brightspace OAuth 2.0 App

Using Postman with Brightspace requires a Brightspace OAuth 2.0 app. If you do not already have an OAuth 2.0 app, you can either create one in your instance of Brightspace by navigating to How to get started with OAuth 2.0, or use the public app provided in the Brightspace Development Environment (make sure you Join the Developer Group to access the “Developer Instance Credentials” file, which contains the OAuth 2.0 public app details).

Creating a Postman Collection and connecting it to Brightspace

Prior to starting, make sure that you have installed Postman. Use the following steps to set up Postman authentication with your Brightspace app:

Launch Postman.
You should be prompted with a Getting Started window. Under the default Create New, select Collection.
Specify a Name for your new collection (e.g. “Brightspace API Testing”).
Select the Authorization tab.
From the Type drop-down, select OAuth 2.0.
For the Add auth data to drop-down, select Request Headers.
Click Get New Access Token.
The Get New Access Token window opens. You will need to configure each field as follows:
- Provide a Token Name value (e.g. “Brightspace Dev Environment Token”).
- Grant Type set to Authorization Code.
- Set the Callback URL to: https://oauth.pstmn.io/v1/browser-callback (as per Postman OAuth 2.0 documentation)
- Set Auth URL to: https://auth.brightspace.com/oauth2/auth
- Set Access Token URL to: https://oauth.pstmn.io/v1/browser-callback
- Client ID should match the Client Id value from your Brightspace App.
- Client Secret should match the Client Secret value from your Brightspace App.
- Scope should match the Scope value from your Brightspace App.
- State can be any value. This value is a security feature meant to protect against Cross Site request forgery. For testing purposes this value is not very important; but for production apps ensure that you use a cryptographically secure value.
- Client Authorization set to Send as Basic Auth header.
- Click Request Token. You will be prompted with a login window for your instance of Brightspace. Enter the Username and Password of the user you wish to perform API requests as and click Log in. If successful, you should see a consent prompt to confirm the application use. Accept this prompt (note that this prompt only occurs for a user the first time they access the app).
The window should close and you will see an Access Token value entered into the collection. Scroll to the bottom of the window and click Use Token.
Click Create to create your Collection.

You now have a Postman Collection connected to Brightspace using OAuth 2.0. The next step is to add an API Request to your Collection.

Adding Brightspace Requests to your Postman Collection

One of the powerful aspects of Postman is that you can add one or many API Requests to a Collection.

To add a request to your Collection

Click New.
Select a Request and enter a Request name and Request Description.
Ensure your Collection is Selected as the save location. Click Save To {your Collection}.

At this point you will be brought back to the Postman landing page, but now you have the option of adding a specific API request. You can supply Postman the details of any Brightspace API route you want to test at this stage. You can add a Request to GET a list of all quizzes that exist in a specific course.

For the first field specify GET as the HTTP method.
In the Request URL field, you need to build the full API endpoint. This includes the instance URL.
1. Start with your instance URL.
2. Enter the URL of the API you want to call (e.g. /d2l/api/le/(version)/(orgUnitId)/quizzes/ ).
Substitute the (version) value for your current API version.
Substitute your orgUnitId for the course to target.
Click on the Authorization tab and ensure Inherit auth from parent for Type is set.
With the request details entered and the authorization specific, click Send to test the new request.
You should now receive back a 200 response with a series of quizzes currently available for your user to see in the specific orgUnit.

If no quizzes exist, you can expect a 404 error for no quizzes found. If your user does not have permissions to see quizzes, you will receive a 403 not authorized error.

Advanced Uses of Postman

Postman contains additional features that both save time and increase understanding of an API route. Postman allows for Collection and/or Environment variables. These enable you to substitute values into your requests for quickly adding new endpoints or testing in different instances. Here are some ideas to help you get started:

Create an environment variable that defines the URL of your Brightspace instance
Create a version variable to store the value supplied in your API URLs

Another great feature is scripts. Postman contains a runtime environment (based on Node.js) that allows you to add dynamic code to your requests either pre-request or right after a call is made. Users can add pre-request and post-request scripts to collections folders or specific requests. Scripts are great for situations like:

Polling for an instance’s API version and supplying the value into a variable for a subsequent request
Saving the value of an OrgUnitId and passing it for a lookup in a following request
Performing a calculation function before submitting the data in a POST API

Issues with Postman and Brightspace

Our evaluation of Postman was promising and positive. However, we did experience a couple of issues that you should be aware of.

Clearing Cookies: At the time of publishing this article we have noticed that there are no issues the first time OAuth tokens are generated. However, subsequent attempts have issues. To resolve this issue, we recommend to Clear Cookies within Postman.

No Login Redirection: When generating an OAuth token, the user is sent from Postman to the login page of the Brightspace instance they are developing against. There are no options for redirecting to a different Brightspace login page within Postman’s built-in browser. This is only an issue if the user account you are developing with is not registered with the Identity Provider of your main login page.

We are evaluating both above issues. However, we believe they are both issues within Postman. We would be open to suggestions on how to better bypass these issues, and we will provide any updates we receive in this article.

Conclusion

Let us know about your experience using Postman and share with us any Postman Collections you develop. If there is another API testing client that you prefer over Postman, we would like to know so we can also test it.

For more training on using Postman, refer to Learn Postman with Paul.

Figure: View the details of a request on the request screen.