Learning Canvas API

[9931696]

Hello - I was seeking recommendations or advice on the best approach to learning Canvas API. I have a technical background, I just want to learn more about the functionality and execution of API calls and how to do it. Any recommendations are appreciated. 

[RaulAlvarez]

I guess the best way to learn about the Canvas API is by looking at their documentation (https://canvas.instructure.com/doc/api/file.oauth.html); it mentions most of the steps and clearly defines the process and parameters required to do it successfully. Also, this is probably by far one of the best resources you can find (https://community.canvaslms.com/t5/Canvas-Developers-Group/Canvas-APIs-Getting-started-the-practical...) by Stuart Ryan.

Another great tool is using the Live API (https://[your_institution].instructure.com/doc/api/live); it lets you play and learn through the different options and see the expected response from the API. Or through the GraphiQL (https://[your_institution].instructure.com/graphiql); a benefit of using this one is that you'll be able to retrieve the information without requiring you to create a token (as in the Live API).

Once you start learning and familiarizing yourself with this, you can start thinking about how to create an app that uses the REST API to retrieve or update the information. However, the API is not set to work directly on the Front End, so you might need to use a workaround like a Proxy or use something directly in the Back End.

I hope this helps!

[AaronWong]

I took the dive into the Canvas API about a year ago. I used this link as a resource:

https://community.canvaslms.com/t5/Canvas-Developers-Group/Canvas-APIs-Getting-started-the-practical...

It was good, but it wasn't as great for me as the comments in that thread suggested it would be. By the time I got to the end of the page, I still felt like I didn't actually know how to do anything.

(And I actually recommend against reading the documentation to start. I know it's a common recommendation, but I have found that you need a certain threshold of background knowledge/experience before you the documentation is helpful, and a lot of people don't meet that threshold.)

I came to this with 20-something years of general programming experience (mostly in Python, though I dabbled in other languages) but absolutely zero API experience. I was initially thinking that the API something like a programming language for Canvas, but that's not quite what it is. There is a limited number of very rigid commands you can give the API, and you have to figure out how to do what you want to do within the confines of those commands. However, you can use an actual programming language to do execute complex sequences of API commands and do things with whatever information you get out of the API.

I think the two most important pieces of information are knowing what your programming background is (what do you mean by a "technical" background?) and also what your goals are.

If you have a programming background, you'll want to figure out the tools you have within that language that allow you to use HTTP requests (PUT/GET/POST). I used the requests package for Python. There were a lot of basics here that I needed to understand to get started, and I don't know whether the Canvas-specific guides will be of much help there. If you use a different language, I'm sure someone around here can help you with those things.

If you don't have a programming background, it's a bit more complicated because you're kind of learning two things at the same time. I won't say more about that here, but it basically pushes this conversation in a completely different direction.

But regardless of your programming background, the other question you need to be able to answer is "What do I want to do with the API?" And maybe your answer is that you don't know and you just want to explore. That's kind of like saying, "I want to do arts and crafts" but not knowing what sorts of crafts you want to make and you're open to try anything. In that case, you might just try to learn how to do simple things that have already been done, and that's perfectly acceptable as a starting point. Basic things you can do are get a list of your courses, send a message, and add a new page to an existing course. And as you start to do those things, you might start to imagine how to combine them together in some way that's useful to you. (By the way, my first project was "Make a gradebook" which I thought would be easy but turned out to be more complicated than I imagined. But I still learned from it, and that's really all that matters.)

If you have a particular goal in mind, you need to figure out whether the commands exist for you to do that. And you can read a bunch in the documentation, but it's probably quicker to just ask. Sometimes, things are not organized in the way you might initially guess. Although I haven't interacted on this community a ton, I've found it to be supportive and helpful, even if you're not completely making sense or completely understanding what's happening.

Good luck!

[Code-with-Ski]

I found it useful to use Postman to experiment with the API calls on the test/beta server.  GET calls are the safest to work with since there is no risk of changing data, especially after you start working on production.  The Runner feature in Postman is also convenient for repeating an API call in bulk based on a source file.  For example, you can download a provisioning course report with Postman Runner (after you set-up the appropriate API call with variables), to publish all the courses.  Here is an article from freeCodeCamp with a walkthrough tutorial on making your first API call using Postman and the PokeAPI: How to Test and Play with Web APIs the Easy Way with Postman Another nice feature about Postman is you can get the script equivalent for the API calls you set-up in various languages.

I found the following video tutorials useful when I was getting started with learning about APIs:  

• The Coding Train: Working with Data and APIs in JavaScript 
• Python and REST APIs: Interacting With Web Services 
• Instructure YouTube Channel
  • You can search for "API" to find past InstructureCon presentations related to the Canvas API.  Even though some are fairly old at this point, they usually still have useful information for when you are getting started and seeing some of the potential things you can do with the Canvas API.
  • You can also do a search for "JavaScript" to find past presentations that may be useful when you are trying to get started with theme modifications too

As @RaulAlvarez shared, the Canvas API documentation is important to use to learn more about what data can be accessed/modified, the required format for requests, and the expected format of results.  If you use your browser's developer tools, you can also monitor Network traffic while using Canvas and see how they are using APIs to load some of the data and update data based on user interaction.  Not everything can be done with the API, but there is a lot you gain access to with the API.

I would also encourage taking time to explore the Canvas Community, especially the Canvas Developers group.  I learned a lot from reading code samples and scripts people have shared and discussed.  @AaronWong shared one example of a useful resource in the Canvas Community, but there is a lot you can learn from once you start exploring.

[AshlyPadgett]

Also been wondering this too @9931696 , thanks so much @RaulAlvarez , @AaronWong , and @Code-with-Ski for the recommendations and resources to get started!! I initially hoped intro training videos or a training course existed, but haven’t found any so far. Sadly, it’s difficult to find any Canvas API “Getting Started” videos.

I’d love if practical intro videos or Canvas API Code-along videos existed, that walked an admin/instructor through an example Canvas API use case (e.g. how to scan course content, how to edit a feature, etc.)! If anyone knows of any, or makes these types of videos, I’d love recommendations!! Otherwise, I guess I’ll have to make some myself once I get good enough! 😄

[chriscas]

Hi @AshlyPadgett,

I can tell you there is an API elective course available as part of the Canvas Certified Technical Admin certification program, if you're interested in that.  It is a paid certification program for Canvas admins, so perhaps your school/institution would provide some or all of the funding for you to get the certification.

Around the API in general, I agree with what others here posted already that there is a bit of a catch-22 situation around getting started.  The API has so many components that it's hard to really dive into the entire thing without some kind of project in mind, but on the other side it's hard to know what kind of project the API could be useful for without knowing more about it.

I do see some people thinking the API will be able to do much more "magic" than it really can.  I think the way I would describe it is that it will be able to do almost anything you can do through the Canvas web interface, just in a more programmatic way. So, if you wanted to, for example, change the title of all of your courses, the API could do that because you can do that on the web version of Canvas.  But if you wanted to rename the "Assignments" menu to something else, the API would not be able to do that, since that's not an option Canvas has at all.  There are a few exceptions where the API might be able to do something that's not in the web version of Canvas, but that is more of the exception than the rule.

I think a lot of API use is to do things in bulk and/or on an automated schedule.  I'll give some examples of what I personally use the API to accomplish:

• Through a python script what runs once per day:
  • Ensure course dates are accurate, and fix them if not (we want all of our courses to be locked to the term, and even with the options set correctly in Canvas, the import tool can adversely affect course dates)
  • Ensure certain course settings are the way we want them (no public visibility, for example).
  • Ensure faculty enrollments are consistent with our SIS, as the sis import process itself is not able to do that the way we have our push configured.  This runs a Canvas enrollment report, then compares that with the latest SIS import files to find and handle discrepencies.
  • Delete courses that are over 7 years old (and notify users about the upcoming deletion 60, 30, and 5 days ahead of time).
• Through a manually run python scrips
  • Change LTI settings which are not exposed in the UI.
• Through the custom theme Javascript:
  • Determine the user's exact role.

Hope this info sheds a bit more light on some possibilities!

-Chris

[AshlyPadgett]

Oh wow, I didn’t know about the API course / Technical Admin Cert! Thanks so much for sharing some of your example use cases @chriscas , this is super helpful for better understanding Canvas API's potential! The course dates and settings check sounds great for catching issues and would be a big time-saver for Course QA, I’ll definitely want to look into that for the future! Thanks!!

[9931696]

Thanks @chriscas I was looking at the certification. I just know there is functionality in the API arena and I want to ensure we are taking advantage of the possibilities! thanks...

[matt2]

I'd recommend getting a solid understanding of HTTP and REST APIs in general, and the Canvas API documentation will make a lot more sense. FreeCodeCamp has a great beginner's tutorial on REST APIs here. Once you've done this type of work with a REST API, you'll be able to work with most REST APIs without too much trouble.

I'd also suggest you start with a simple goal in mind to get started. The entirety of the documentation can be overwhelming so trimming your focus down to a simple goal will help you navigate that. For instance, let's say you need to be able to programmatically retrieve the details of a course in Canvas. The steps to achieving that are something like:

1. Pick a language - Python and PowerShell are common choices, but pretty much any programming or scripting language today can do HTTP requests.

2. Get an API token - that's documented, so just follow those instructions. And make sure you protect that token accordingly. 

3. Craft your authentication header - you'll need to authenticate to the API in order to retrieve information or perform actions.

4. Make your first real request. This will mostly just have a few elements: a request URL, an authentication header, and a method (GET to start with). A simple request for courses in PowerShell would look like this:

$Parameters = @{
    Uri = 'https://domain.instructure.com/api/v1/courses'
    Method = 'GET'
    Headers = @{Authorization = "Bearer <your API token>"}
}
Invoke-WebRequest @Parameters

After this, you'll be able to dive deeper into the API docs as your needs dictate. Focus on the "Resources" list as this details each type of object you can retrieve or manipulate.

At  some point you may also need to look into pagination. This is a little difficult the first time but once you wrap your head around it you'll be able to build a routine to handle paginated results fairly easily.

[ErnestChan]

Hi all,

I just start reading and learning about Canvas API lately and have some basic Vanilla JavaScript and API experience before.  

I have a question about learning Canvas API. It seems like we need to use either JavaScript or Python with Canvas API in most cases. which programming languages would you recommend? thanks.

- Ernest

[matt2]

Ernest,

REST APIs are generally language-agnostic - any language that can work with HTTP can generally work with a REST API. JavaScript and Python are often used for examples because they are fairly ubiquitous among web developers. What language you use for REST API tasks is really up to you and should be based on what makes the most sense for your work and fitting your IT environment. Go with what works for you!

That said, if you need language-specific help in this forum, it's likely that JS or Python are your best bets as others on here might have experience with the Canvas API using those languages.

[melodyc_lam]

@ErnestChan 

Like @matt2 said, the API is language agnostic but most of us on the forum (including me) work in Python and/or JS.

There is an amazing library called CanvasAPI that is written in Python that a lot of us use/started with as it covers almost everything in the Canvas API and is a good way to learn some of the API calls. I've "grown out" of the library as I've been doing things such as SIS imports/exports that need a little bit more control programming wise, but I wouldn't be here without their open source library!

In another life I was a computer science teacher and taught Python and Java (and a little of JS) and with the requests library in Python being one of the easiest ways to enter into HTTP calls, I stuck with Python as my language of choice. However, programming languages are really just different ways of saying the same thing so even if you're familiar with another language you should be able to pick up a snippet and translate it to the language of your choice.

Hope this helps!

[ErnestChan]

Thank you for your wonderful insight on using Canvas API. It seems like python has more online resources than Javascript for Canvas API and I think I would go to the Python route rather than JS. As a self taught programmer, I am wondering whether you have any good learning resoures for python? my go to learning platform is linkedin learning since it is free to access with my local library card. 

- Ernest

[melodyc_lam]

You can see if this MOOC from the University of Helsinki works well for you (it's in English and it's free)

You can also check out the r/LearnPython subreddit here for more resources.

Make sure you learn Python 3 and NOT Python 2! Python 2 has slightly different syntax in places, so you don't want to learn Python 2 and find that it doesn't work in Python 3.

Hope this helps!

[matt2]

If it helps, I found this quick reference article from Packt publishing that illustrates how to make a basic REST API call in 7 different languages.

https://subscription.packtpub.com/book/web-development/9781786469243/1/ch01lvl1sec11/using-rest-in-d...