Spencer Varney

PowerShell API Client - looking for input

Discussion created by Spencer Varney on Aug 21, 2017

Good day!

 

tldr: I made a better PowerShell API client, hope folks will test it out and help me find a better way to solve the naming conventions of the Cmdlets.

 

So I made a post earlier this year about an experiment of generating a full, comprehensive PowerShell API client by scraping the documentation pages. It was OK, but honestly I still found myself just using the manually written cmdlets I had. Then in a comment Colin Murtaugh mentioned the existence of a Swagger doc that, holy crap, was exactly what I needed.

 

I've finally gotten around to finishing this here and there, and I'm happy to say it's mostly working! In roughly 10 seconds you can generate your own Canvas API PowerShell client, it's pretty neat and much less hacky! The repo is here with short instructions on how to generate your own. (Bonus - There's also a manually-written file for the Canvas Data API.)

 

One issue though - ultimately I'd like to post about it on the Admin Community, but it's still sorta hacky. Mainly, PowerShell requires that each Cmdlet have a unique verb-noun name, like Get-CanvasUser. Which is fine, except I couldn't find a consistent way to do this and resolve duplicates and ambiguities. I turned to parsing the API paths, so for instance:

GET /v1/accounts/{account_id}/users/{user_id}/account_notifications

 

becomes:

Get-CanvasAccountsUsersAccountNotificationsByAccountIdAndUserId

 

It's unique and works, but it really makes usability an issue, nobody is going to want to use that. The result is a pretty hefty doc with [seemingly] functional Cmdlets, but confusing names. Anybody have good ideas there?

 

Let me know what you think, I'd be happy to chat about it and make it better! I'm also pretty bad at remembering to use the Communities, so feel free to also reach out via email or GitHub

 

Thanks for reading, enjoy your day!

 

Spencer

 

Edit: haha check this gem out though: Put-CanvasUsersMergeIntoAccountsUsersByIdAndDestinationAccountIdAndDestinationUserId

Outcomes