cancel
Showing results for 
Search instead for 
Did you mean: 
Highlighted
Surveyor

Canvas API and Swagger

Jump to solution

Looks like Canvas is using Swagger as the API definition format. and judging by the Live API (https://<canvashost>/doc/api/api-docs.json ) it is using Swagger version 1.2

My question is does anyone know how to generate a (C#) client library based on the API definition from Swagger.

There are some options out there on the Internet like NSwag, but they all work against Swagger 2.0.

I have also tried to convert 1.2 to 2.0 using converter like https://lucybot.github.io/api-spec-converter/ , but that doesnt seem to work either.

thanks

Doug

Labels (1)
Tags (2)
1 Solution

Accepted Solutions
Highlighted
Community Coach
Community Coach

Hi d.tan@auckland.ac.nz,

Great question, this is something I have often wondered myself. tnijssen@ucsc.edu, that is handy to know!

Perhaps if this is something that more people would like to see in a future version of the API, logging a feature idea for this would be outstanding. I would suggest leaving the discussion open for a while first, and then collecting all the thoughts into a feature idea, what it would deliver, and how it would benefit all who interact with the API.

Cheers,

Stuart

View solution in original post

10 Replies
Highlighted
Surveyor

It turns out that Canvas' API specification is just something that looks like Swagger 1.2, but doesn't actually follow the standard.

The farthest I've gotten is converting the Swagger 1.2 spec into something that looks like Swagger 2.0 (but doesn't validate, with unhelpful errors). I hadn't even gotten to the codegen phase yet.

If/when Instructure ever create API v2, maybe they can use Swagger 2.0 (or at least something that actually validates).

Highlighted
Adventurer

Is there any plan to update the Canvas API swagger specification to a more recent version?

Highlighted
Community Coach
Community Coach

Hi d.tan@auckland.ac.nz,

Great question, this is something I have often wondered myself. tnijssen@ucsc.edu, that is handy to know!

Perhaps if this is something that more people would like to see in a future version of the API, logging a feature idea for this would be outstanding. I would suggest leaving the discussion open for a while first, and then collecting all the thoughts into a feature idea, what it would deliver, and how it would benefit all who interact with the API.

Cheers,

Stuart

View solution in original post

Highlighted
Community Coach
Community Coach

Hi d.tan@auckland.ac.nz,

I wanted to check in and see if the previous answers have given you the information you need? For now I will mark this as assumed answered, however if you have any additional questions, please do not hesitate to jump in and let us know.

Cheers,
Stuart

Highlighted
Community Member

I would love to see Swagger 2.0 support in Canvas. Having a Swagger 2.0 spec would allow is to dynamically create clients based on the Swagger documentation. 

See:

GitHub - RSuter/NSwag: The Swagger/OpenAPI toolchain for .NET, Web API and TypeScript. 

GitHub - Azure/autorest: OpenAPI (f.k.a Swagger) Specification code generator. Supports C#, Go, Java... 

Highlighted
Adventurer

There was a hint from Simon Williams(Instructure) at Intrusturecarn this year that they are looking at supporting OpenAPI (upgraded and renamed Swagger API) in the future, although because their API has evolved over time, rather then being designed with Swagger/OpenAPI in mind this isn't a simple/easy process. The video of this is here:

https://www.canvaslms.com/instructurecon/video/2018/?video=mun6emoc1u 

I've managed to generate a client by upgrading the Swagger 1.2 spec to 2.0 and then tweaking it. But it needs quite a bit of tweaking to get a working client and then this progress has to be repeated when the API is changed.

Highlighted
Explorer III

I filed a Feature Request that I hope captures this - https://community.canvaslms.com/ideas/13768-api-in-openapi-format 

Highlighted
Community Member

Ok so I know how to make this work but its on an API by API basis, not the whole lot at once.  

go to https://<Your Canvas DNS>/doc/api/api-docs.json 

Find the API you want in the list and cut and paste the path to replace "/api-docs.json" i.e. for users it becomes

https://<Your Canvas DNS>/doc/api/users.json 

Cut and paste that URL into Postmap Import -> "Import from link"

This will generate a Valid API collection with a couple of limitations.  All the URL's are "canvas.instructure.com" and it will import all the API's related to that.  The "user" collection for example contains EVERYTHING to do with the user even if in api.instructure.com its listed under another object.  There also appears to be undocumented API's in here I think, haven't looked closely at it yet

Highlighted

Another way is to look at the XHR requests in your browser console when you access that page, but actually, since the Requests come in with canvas.instructure.com, you can just look at https://canvas.instructure.com/doc/api/api-docs.json.

Just as an example, here's a screenshot from Postman after importing one of them. I had to edit each request to use our domain, although in fact, I use an environment variable, so the requests look like: 

https://{{domain}}/api/v1/accounts/:account_id/sub_accounts/:id

Canvas API Requests in Postman