API Testing: Postman

[garth]

This information is really geared towards users who are trying to get started with the API.

I have seen questions in the community about the API, and have see Postman mentioned many times.  But, searching the Community I have not found any posts specifically about this tool and feel it might be worth talking about for those looking for a starting point.  My hope is that folks who are experienced with the tool can add to this information and further help new users get up to speed.

Postman Web App

Postman is easily accessible in Chrome through the Web Store.

If you haven't installed an app in Chrome before take a look at this article:

Install and manage apps - Chrome Web Store Help

To find the Postman web app and install it, search the Web Store for "Postman"

Postman Native App

Postman also has a native app that you can install directly, which can be downloaded here:

Postman | Supercharge your API workflow

Personally I have not downloaded the native app yet, and have exclusively used the Chrome web app so far.

Postman provides documentation on installing the Chrome web app and the native app here:

Postman Docs - Getting Started

Authenticating With Your Token

To make an API call you will need to use your developer token to authenticate.

The following screen shot illustrates how to use the Headers to submit your token.

1. Click on the "Headers" tab
2. Enter the value "Authorization" for the key
3. Enter "Bearer <token>" as the value

This screen shot also shows an example of the syntax to get a list of enrollments for a specific course, which you might want to use to test your token.

Example of a GET

You will need to tell Postman what type of API call you are making, i.e.GET, POST, PUT, whatever HTTP verb is associated with the API call.  The following screen shot shows an example of making a GET call to get the current status of an asynchronous job:  Progress - Canvas LMS REST API Documentation

In this case the API call is asking for the status of a content migration request.  You can see that GET has been selected as the type of API call being made, the authorization token has been provided, and the json results are displayed.

Example of a POST

This is an example of a POST command to copy course content into another course:

Courses - Canvas LMS REST API Documentation

Notice in this screen shot that POST is selected.

Example of a PUT

This might be useful, an API call to update a course:

Courses - Canvas LMS REST API Documentation

In this example, I am passing a parameter to publish/unpublish a course (which is useful in a script to publish all courses at the beginning of a semester).  Notice this time that PUT is selected in Postman.

API Results

API results come back in JSON format.  JSON is notation representing object data.  If you are not familiar with JSON take a look at this W3Schools page for an overview:

JSON Syntax

W3Schools also has a tutorial here:

JSON Tutorial

Conclusion

This is basic info to help someone get started.  There is so much  more you can do.

Search Google for video walk-throughs to provide additional details.

Look through the Postman docs for tutorials and advanced techniques:  Postman Docs

Hopefully the info here will get you started, and community members will add their tips and tricks.

2016.11.14 - Update

If you would like to see source code showing how to implement the API in .NET, I have posted here:

• .NET - Canvas API Implementation​

For those who are interested in automating admin tasks and reporting, this might be useful.

[shane_ohara]

Excellent information in here, Garth. Thank you for sharing the knowledge forward for others to use. I do want to mention that it might be a good idea to think about getting away from the Chrome app in lieu of the native app because of http://venturebeat.com/2016/08/19/google-will-kill-chrome-apps-for-windows-mac-and-linux-in-early-20...​.

[garth]

Excellent point, I started a discussion a while back on this if others are interested: New Chrome apps will be available only on Chromebooks

Thanks for bringing this up!

[twheeler]

When Chrome Apps go away you'll still be able to use many of them them by going to the websites. PC users won't have access to Postman, but for Mac users its a stand alone app.

[twheeler]

Actually Postman already has a stand alone app for Windows. If you go to your cloud dashboard it only show Mac and Chrome, but their app page has them all.

Postman | Apps

[garth]

Ya, I like having the Chrome apps though, easy access without having to manage a bunch of stand alone installs, it makes me sad : (

[ptart]

Has anybody had any luck using Postman to use the results from a GET request to run a POST request?

I'm trying to get the section_id for a course and then use that to cross-list it with another course.

For example:

1. GET {{url}}/api/v1/courses/123/sections  -  (this will return section "id":222 for course 123)
2. POST {{url}}/api/v1/sections/222/crosslist/111  - (this will cross-list section 222 into course 111)

I'd like to run this once instead of having to copy the section id into another request and then run the POST request.

[garth]

 @ptart  Postman is a great tool to test your syntax for the API call.

I have only used Postman to validate API syntax.

You can also do some basic unit testing with Collections:  Postman Docs

Looking at the documentation, it seems you can pass in static variables from a file, but this does not help your scenario where you need to feed results from one API call into another API call.

As soon as you need to implement logic around your API calls you should start thinking about scripting, like JavaScript.

JavaScript would allow you to inspect the results from your first API call to get the section id, then feed that value into your secont API call as a parameter.

Search the community for posts on what others have done with scripting and you will find some good examples.

[dgrobani]

What Garth Egbert said! I find Postman invaluable for working out the correct way to make an API call, but I think your time would be better spent learning a scripting language than figuring out how to pass data from one call to another in Postman.

[tdarrow]

This was exactly what I was looking for. I was introduced to Postman, but couldn't figure out how to use it. Thanks for providing examples!

- Tim Darrow

[sonya_corcoran1]

Thanks  @garth  , your guides are most helpful for newbies starting out!!! I really appreciate that you don't assume knowledge and walk us through step by step.  All up and running on Postman native and loving it. Going to come in super handy...thanks again

[ptart]

Garth,

Thanks for the tip. I have been learning JavaScript and am using Postman as I learn. The key was learning about snippets to set the variables in Postman. Now I can use Runner to load a .csv file with the correct headers and have Postman run through the list making the appropriate API calls and tests.

Having said that, I am still working on my JavaScript knowledge to do more to improve my workflow. Google App Scripts have been really useful as well.

Thanks for your advice!

[glparker]

Wondering in anyone else is seeing this error.   I'm attempting to set the Authorization Bearer <token> header, using a token that I know works from using elsewhere in scripts, but I'm getting an error in Postman

   Error while sending request: Failed to execute 'setRequestHeader' on 'XMLHttpRequest': 'Bearer <TOKEN>' is not a valid HTTP header field value.

Hope someone can point to what I'm doing wrong.  Thanks in advance.

Glen

[MattHanes]

I was trying to compare my Postman screenshots to yours and the only difference I notice is you have two areas to enter a key and value in your screenshot. I only have one. Maybe that has something to do with it?

[glparker]

  There was a newline at the end of my key, and that was what was tripping up Postman.   I spotted it when I clicked the Code button to view what was being sent, and noticed a blank line 4.   Thinking that was weird, I clicking on the Value section and found there was indeed a trailing new line.  Remove it, and the example worked.

Lesson learned, hopefully this helps someone in the future.

[garth]

 @glparker ‌ great scenario to share, thanks for posting.

[ptart]

I found it extremely helpful to setup environments so that I could run the same requests against production, test, or beta without changing my API call. Variables make Postman all worthwhile and much easier to use. Later, I found out how to use these variables to make multiple API calls one after another using the results from a prior API call.

See Setting up an environment with variables in Postman.

In each environment (production in these screenshots), the basic variables I started with were:

1. url = https://domain.instructure.com/api/v1 (replace domain)
2. token = 😉 insert your own token here.
3. Add any others you want and name them what you want.

When making an API call, your call starts with {{url}}. That goes to your variable and puts the url already set.

Set your Headers as Authorization = Bearer{{token}}. That pulls your token to authorize the request.

Now your API calls are much cleaner and it makes using the Canvas API documentation so much easier.

If you leave /api/v1 off of your url variable, then you'll be able to copy the call right from the Canvas API documentation and paste it into Postman so it will look like {{url}}/api/v1/courses then you fill in the rest.

[garth]

 @ptart ‌ excellent information, thanks for posting.

[jcrawford]

 @glparker ‌ I'm removing the blank line, but it doesn't seem to "save."  I keep getting the same error message and when I click Code, the line is still there.  What am I missing?

[dwillmore]

I use Postman to do some dirty data pulls from Canvas.   Is there a way to handle multiple pages of data in a 'get' when using Postman?   I can't seem to find link headers when I try to pull pageviews for user.

[garth]

 @dwillmore ‌ th elink headers can be found on the "Headers" tab, screen shot below.

These headers should line up with the API documentation on Pagination

I hope this helps.

[dwillmore]

I feel more than a little foolish.  Thanks for the quick answer.

[kevinw]

Hi there, I'm brand new to making API calls and to postman. I've been doing some testing in beta and I'm trying to run this post to create a new course:

POST ******.beta.instructure.com/api/v1/accounts/1/courses?course[name]=Test One&course[course_code]=42

But when I send this all it does is return me a list of courses and nothing is created. What did I break? 

[garth]

 @kevinw ‌ I just tested your API call using Postman, and was able to successfully create a simple course with the two parameters you have given in your post: 

• course[name]
• course[course_code]

Here is a screen shot of my Postman setup, make sure you have "POST" selected as the HTTP method (red box in screen shot).

In my example, I created a course with the name "API Test Course", and the course code = "API-TEST-COURS"

You can see the result returned by Canvas in the screen shot.

Let me konw if this helps.

[kevinw]

Now I'm just really confused because *I think* I followed your directions to a T.

You can't tell by looking at it but all I'm seeing in the body is a list of courses in the account. It's acting like I ran a GET. 

[kevinw]

BINGO! I got it. I had to type https before my URL. It was sending it by default through http. Thank you!

[kevinw]

Found the solution here. Apparently if you don't specify https it drops all the POST variables. 

[garth]

Awesome!  Glad you figured it out, it's easy to overlook.

One of the best resources you have is here:  Canvas LMS REST API Documentation 

And the fun begins

[kevinw]

Hey  @garth ‌, 

Sorry to bug you again. Suppose I wanted to make multiple things at once. I've successfully created a user with a password and login, created a course, enrolled teachers and students in that course, and published the course. But these all take separate actions.

If I wanted to write this up all at once and run it through the API, how would I do that?  

[garth]

 @kevinw ‌ Postman as a "Collection Runner", here is a short video overview:

• How to use the Postman Collection Runner - YouTube 

Follow that up with this tutorial:

• Updated: Using Variables in Postman Requests & Collections - YouTube 

If your requirment is more complex, then you likely need to write your own business logic around the API calls.  There are many options, including JavaScript, PHP, Ruby, pretty much whatever language you are comfortable with.  Personally I have years of experience with .NET, so that is my tool of choice, I am able to quickly create new workflows with C#.

If you haven't met  @James ‌ yet, search for him in the Community.  He has posted multiple articles regarding the use of JavaScript.

[kevinw]

Hey Garth, Garth-Vader, Gartham's hero, Garthy McGarthGarth, 

Sorry to bug you again. It seems as if I would have ran into my limit trying to make custom reports from postman. Am I wrong in thinking this? I'm checking out the documentation now and I've tried a couple of posts and I keep getting an error but perhaps I'm having trouble with the syntax or I've missed something. Here is what I tried

https://garthrules.instructure.com/api/v1/accounts/1/reports/enrollments=true&users=true

[James]

 @kevinw ,

I don't know if Garth gave you access to his Canvas instance or not, but if he didn't, then it's highly unlikely that your Canvas instance is named garthrules.instructure.com. If it isn't and you don't have access to his site, you'll need to use your host.

Then, if your account isn't #1, you'll need to use your account number or use "self" (without the quotes).  If you open up your web browser, log into Canvas, and add "/api/v1/accounts/self/reports" to the end, you'll now have the URL that you need to use to make the API call. You can actually go ahead and hit enter if you like and look at the results in the browser (although modern Firefox browsers may need a tweak to get rid of the while(1){} in front.

The endpoint you're using looks like the one for starting a new report. If so, you need to give the name of a report, which is contained in the "report" property that's returned from the list available reports. You haven't done that.  The report names often end in _csv, like "provisioning_csv".

What it looks like you're trying to do is supply parameters and that enrollments=true and users=true are two that you're trying to use. However, parameters come after a ? in the URL, but you don't have the ?  

Normally, though, when you're making a POST, you don't use the query string, although I think it's technically allowed. But the point is that you need to make sure you're using POST if you're creating a report.

If you're trying to get the status of a report that you've already created, you need the name of the report (like "provisioning_csv") and the ID of the report was generated when you made the request to start it. You can also get that by requesting a list of all of the reports.

[garth]

 @kevinw ‌ it does look like a syntax error.

Start with this API call to get a list of possible reports:

• Account Reports - List Available Reports 

The syntax / Postman string should look something like this:

 

Scroll throuth the results for the variable "report", that's the name you want to use in the next API call.

But, before moving on, also notice the next parameter: "last_run", which also includes the parameters that were sent.  This will help you to get the parameter names right for your API call.

I suggest running a few reports from the user interface, then use this API call to see if you can find your requests.

Now, I suspect you are going after the provisioning report, which will look like this in Postman:

Notice in the result it tells you "progress": 0

It is up to you to monitor the status of the report, until that value is 100, i.e. 100% done, then the "file_url" will have a download link.  If you look at all of the return values from your results in the first query above you will see "progress": 100, and the "file_url" as examples of what to look for.

To monitor the report status you will have to loop and make multiple calls to this API until the report is ready:

• Account Reports - Status of a Report 

I hope this helps.

 @James ‌ if I had the domain "garthrules" that would be pretty cool, but I try to adhere to everyone's rules

[kevinw]

ah-ha   

Yes thank you both very much. This clears things up. It seems I will also have to confiscate a jamesrules.instructure.com in the near future. 

[dwesterv]

We have created console apps in .NET for our business logic. I really like the flexibility as well as debugging! I would highly recommend.

[garth]

 @dwesterv ‌ it's great to meet another .NET dev!

In the realm of Canvas I have used .NET to create a workflow engine allowing us to schedule and automate routine admin tasks, several LTI apps, and a portal app similar (but different) to Catalog.  .NET is a powerful tool for sure, I definitely feel spoiled by Visual Studio.

Thanks for the post, I encourage you to share tips/tricks you have learned, there aren't a lot of .NET contributors 

[dschuma]

At BGSU we have used Postman and the API to diagnose issues and make data changes for years.  The desktop version has more features than the Chrome app.  Thanks for creating the article!

[BenGirard]

Could someone share the PostMan Collection for Canvas? I don't want to create hundreds of API calls manually.  Thanks.