Generating a Canvas API Client - an experiment

[svarney]

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?

[dgrobani]

Wow, what a fascinating experiment! I don't have a use for it in my work, having written my own set of Python API wrappers, but I'm really impressed. Reminds me of Pandarus.

[svarney]

Oooh, thanks for the link! I'm curious to see how they handle things, but from experience PowerShell runs into special troubles that you don't see in other languages (for example, you can't overload methods - they just get overwritten). Either way that looks to be a great resource, thanks!

[ColinMurtaugh]

Very nice! This is essentially the same approach that we took when we created our Python Canvas SDK, though instead of parsing the HTML, we just read the Swagger spec, which is JSON-formatted and easier to handle.  We did end up having to manually patch some of the generated code in cases where the swagger/api doc wasn't quite accurate, but generally it works pretty well. 

[svarney]

Interesting, I'll have to look into Swagger a bit more - somehow despite all my work with APIs I've never run in to it; I had no idea this was a thing. That said, how did you know it was there? Amusingly, while on a call with a few folks at Canvas I asked if such a document existed (something that gave a complete API description that I could parse to get all of the API information) and was told no.

[ColinMurtaugh]

You know, I don't remember exactly how we learned about the existence of the swagger spec; they really should have some mention of it and a link to it in the API docs.  It seems that it's sufficiently obscure that even some Instructure folks aren't aware of it! Maybe I'll put together a pull request to add it. 🙂

[lauraschauer]

Hi there, 
This is probably about 6 years too late, but I had the same request - a complete API description of the Canvas API in the OpenAPI format (the new swagger). There is none yet, so all I've got is a somewhat outdated one, which has missing endpoints, but works for client library generation. 
If it's still useful to you, you can find it here. Let me know if you've had any updates since 2017 🙂