.NET - Canvas API Implementation

[garth]

What is this about?

If you are a .NET developer and are interested in leveraging the Canvas API to automate tasks at your institution, you might be interested in ths demo project.  I will provide a Visual Studio project that you can download and use as starting point to develop your own tools.

References

I can try to guide you to some reference material for those getting started that will hopefully help.

There are a few basics that would help to understand when working with the associated project:

• Working knowledge of C#: 
  C# Reference​
• What is await? Faimiliarity with asynchronous programming (not required, but loosely referenced in the associated project code):
  Asynchronous Programming with Async and Await (C# and Visual Basic)
• Understanding of HTTP verbs, you might start here if you need some info:
  HTTP Methods GET vs POST vs. PUT
  
• Working knowledge of Json, understanding the structure of a Json object is very important:
  JSON Introduction
• The base classes used to make the API calls:
  • HttpClient Class (System.Net.Http)
  • HttpClientHandler Class (System.Net.Http)
  • HttpResponseMessage Class (System.Net.Http)
• Logging - the sample project uses NLog to create debug and error logs:
  NLog  - can be referenced in Visual Studio using Nuget
  The project includes a sample logging config file
• Newtonsoft Json.NET library - to serialize/deserialize objects
  Json.NET - Newtonsoft  - can be referenced in Visual Studio using Nuget

How does it work?

The associated source code will create a command line tool that accepts a config file.  The config file contains the following information:

• "accessToken" - your access token
• "apiUrl" - the url to your Canvas site, I would you Beta or Test
• "apiCalls" - array of API calls that you would like to run, including parameters

For simplicity and purposes of demo, the access token and API url are in this config file.

The format of the API call list is an array of pipe delimited strings in the following format:

• [method name] | [param1],[value1] | [param2],[value2] | .... | [param(n)],[value(n)]

These strings will be parsed and passed to the API library where they will be converted into actual calls to the Canvas API, at the site defined by the "apiUrl" variable.

This sample config includes GET, POST, and PUT calls, to demonstrate each type of verb.

Each verb is implemented in the base class: clsHttpMethods.cs

Full response details are logged by NLog.  Grab these responses and inspect them for full details.  If your test produces an error or throws an exception, full details can also be found in the log file.  If you use my default nlog.config, log files will be found in this location:  c:\\logs\canvasApiTest\*.log

Comments

The purpose of this project is not to replace tools like Postman, the purpose is to help other developers using .NET to get started with the API.  I tried to keep things as clear as possible.

With myapi.config, I have been able to test any API call I have needed to date.  If you follow my code, you will need to add a C# method to handle each additional API call you want to make.  My "long hand" approach to creating matching C# methods could be modified, but hopefully helps to illustrate the concepts.  Share your approaches.

There is plenty of room for optimization, optimize to meet your needs and share any enhancements you feel people could benefit from.

Project Source Code

Source code can be found on BitBucket here:  Canvas API Implementation​

The source published on BitBucket compiles and runs with Visual Studio 2015 and .NET Framework 4.5.2

IMPORTANT:  Make sure you edit the myapi.config file with your settings, and modify API variable values to match your environment.

All code is provided as-is for demonstration purposes only.

2016.12.03 - UPDATE - File Upload via POST

• I have added a class that walks through the steps of uploading a file.  This code was pulled from another project and put together quickly as a response to a community question, make sure you test failure scenarios in your environment.

[phesse]

Hi Garth,

I have been looking at this code as a possible solution for my LTI app. Thanks for publishing it, btw. I'm running into a roadblock: The solution uses a C# MVC application, and I need to write a solution in an asp.net C# web application. 

I went through the tutorial on setting up the MVC app, and have a basic understanding of it. But as I went through the OAuth code, it's clear that some of the code is specific to MVC. For example, the URI for the POST call (as defined in the xml config file) is "https://my.domain.com/home/Oauth2Request". This is a direct call to the Oauth2Request method in HomeController.cs. I need to know how to do the same thing with an asp.net web application. But I can't call a method directly. Could I point the URI to an aspx page in my web app, and then in the page_load event of the webpage, call the Oauth2Request method? If so, what would the call code be?

Have you done the same solution in asp.net (i.e. non-MVC)? Any help you could provide would be much appreciated.

Thanks,

Pete 

[garth]

 @phesse ‌ the user interface layer is not really important.

On the server side, your web service has to be able to accept an HTTP POST.

My advice would be to create your own web service project to handle your LTI logic, and allow your UI to call out to your web services.  

I used the MVC tutorial because it leveraged a canned user interface, no work needed on the UI side to get started, allowing me to focus specifically on aspects of LTI.

It is really up to you to decide what UI you want to put on top.

[KeithPace1]

Garth - any chance I could hire you to help with a Canvas API application? If so, please respond and we can set up a way to chat. 

[Scott_Dellinger]

To anyone using this code in 2022 and beyond, getting the "No file uploaded" error, you must add the filename to the content when you add the file to the p2Content:

p2Content.Add(new ByteArrayContent(fileBytes), "file", fileName);

You must also check for HttpStatusCode.Created instead of HttpsStatusCode.RedirectMethod.

After figuring that out, things have gone smoothly.