Spencer Varney

Generating a Canvas API Client - an experiment

Discussion created by Spencer Varney on Feb 1, 2017
Latest reply on Feb 17, 2017 by Colin Murtaugh

Hi all,

 

I thought I'd share a little experiment I've played around with in which I attempted to generate the majority of an API Client library for PowerShell. I hope that if nothing else it's entertaining, and maybe it will be of some use!

 

I had a need to use the Canas API recently and was frustrated that I had to actually do work to write methods to call the API endpoints. Eventually, I came to the conclusion that, wouldn't it just be so much easier to generate it? I looked around for a way to do just this and settled on parsing the All Resources page in the API docs and using that as a basis. I also saw that had access to the controller files directly but it sounded more fun to parse the website.

 

The result is a generator written in PowerShell, at less than 300 lines, which can generate over 19k lines of code based on that website. While not all of the generated code is viable (it doesn't yet handle any of the parameters that are awkward or collections or have special markup, for instance) after I commented out about 20 methods it seemed to work well enough! The cmdlets contain the titles and descriptions from the website, if available, which is another reason I chose to not use the controller files, although down the line cross-referencing with those files may make for a much more accurate end product.

 

The cmdlets don't work on their own, they require a hand-written base method (which handles the authentication and making the actual API calls), but that could be imported or embedded just as easy, and you can find that here.

 

One struggle of mine was how to name the PowerShell cmdlets (which need a verb-noun syntax). I eventually settled on using the Http Methods (GET, POST, etc) for the verb and parsing out the endpoints to create the nouns. It's not perfect, there are some duplicates for instance, but hey it's a step.

 

I doubt I'll go much further if there isn't much interest - it's almost better to write just what you need by hand, and custom-tailor it to the need. That said, if anyone is intrigued and wants to see if we can make it better or adapt it to other languages let me know, it could be fun working with others on it.

 

So, what do you think?

Outcomes