New Quizzes Public API: REST or GraphQL?

[TamasBalogh]

Who is this blog post for?

If you or your institution call or plan to call Canvas API for any Quizzes endpoints for automation or third party integration, this blog post will definitely interest you. 

New Quizzes will introduce a new publicly accessible API. We would like to provide the smoothest transition to NQ as it is possible. We’re also thinking about the long-term benefits. We want to hear your voice before making the decision about REST or GraphQL for the New Quizzes API. 

Why GraphQL? Why now?

Why are we thinking about changing to GraphQL and why now? There are 2 main reasons:

1. You may already know that Instructure leans towards GraphQL more and more, eventually all our APIs will be GraphQL based including New Quizzes API.  
2. Currently it’s unknown how much, but New Quizzes API will differ from the current Quizzes API regardless of the choice of API type. If the New Quizzes API is created as REST, the learning curve might be smaller, requiring code changes in a paradigm you're used to. However, you would need to change your client-side code twice in the future. A second update would be necessary when all of Instructure uses GraphQL exclusively.

I believe this could be a good opportunity for future-proofing your code in one step, but want to understand the impact to you.

What is GraphQL?

You may wonder what GraphQL is and why we even talk about it. GraphQL is a query API language that executes queries by using a type system based on defined input data, you can read more about our GraphQL solution here and you can reach the official GraphQL site here.

Main advantages of GraphQL

1. The substance of what gets sent over the wire from server to client is closely related to what you want for your use case both in shape and volume, rather than fetching everything and sorting/organizing on the client side.  This reduces the transmission of data you don’t care about for this specific request, and therefore is more efficient (though the magnitude of that efficiency is obviously proportional to just how much over-fetching happens for a given use case).
2. The ability to flexibly fetch several connected entities in a single request rather than making a request for some entry point you know about, parsing the response, and then fetching children or related entities based on a predicate that could be communicated in a GraphQL query.  This reduces the network overhead of having to make multiple requests.  

GraphQL or REST for New Quizzes API

We would like to hear about your preferences. Please fill out our survey and if you have any additional remarks or questions, don’t hesitate to add a comment to this post!

[eddie_bonetdiaz]

Will moving New Quizzes to GraphQL make it so it can communicate Outcomes data with Canvas core and MasteryPaths?

Will it be possible to integrate New Quizzes in a fashion that resembles other things in Canvas [pages, assignments, etc] so that it's maneuverable while using Modules [i.e. Back and Next buttons to cycle through modules].

Even the backchannels seem to be noticing that Instructure likes to tease the community about new features and access change but be unpredictable about when those changes will occur. So, what is the timeline for this change and access granting? If you don't have a timeline, what is holding them back from solidifying a timeline? If it's the marketing team, although NQ is for paid subscriptions it's still too resource heavy for most institutions to host themselves and freemium users wouldn't have customer support access either. Do they really not understand how much the assessment quality has diminished when NQ became available? 

Being able to track mastery learning alongside the traditional data will be something that will be missed if y'all never fix that issue. 

[SuSorensen]

Hello @eddie_bonetdiaz - 

I’m going to add an assist here in responding to some of your questions. Tamas and I are working closely together to accelerate the Quizzes' evolution. You are absolutely right that solid timelines are not communicated in the community forums. We’ve noticed that the community has experienced a little whiplash with regard to delivery. Therefore, we’re only communicating big ticket items when the dates are near, such as those that appear on the roadmap. For items such as this API discussion, we wouldn’t be able to reliably communicate until the specificity of what is being built is determined; AKA GraphQL or REST. 

As for the New Quizzes workflow integration into the Canvas Modules experience. This is one of the issues I noticed immediately as well. A change for Quiz Takers should be going to beta in the next few weeks. You can watch this conversation or the release notes for updates  Yes, I am again not communicating specific dates in case something emergent causes priority changes. I know that may not be satisfying. We are however committed to making Quizzes extraordinary and know that means listening to users.

[jsailor]

Hi, @eddie_bonetdiaz,

I'll also add to @SuSorensen's response that our outcomes team is aware of the importance in having New Quizzes data pass to the Learning Mastery Gradebook and will have this in place before the deprecation of Classic Quizzes. 

[TamasBalogh]

Hi @eddie_bonetdiaz,

As @jsailor and @SuSorensen most of your questions I'd just like to add that moving NQ to GraphQL (or stay with REST) won't affect New Quizzes' behaviour in Canvas. This is purely for external automations and integrations.

[simpkinsc]

Would love outcomes on new quizzes to be shown in the learning mastery gradebook.

[glparker]

My opinion on this question:   Instructure should not introduce changes to developers in core technologies like GraphQL without sufficient reference implementations the developer community can learn from.     Survey your developers community, identify the top-X languages they are developing in, and build reference implementation projects that they can use to learn from.    Only then should you move forward in promoting/requiring changes to your developer technology stack.

TL;DR Please consider making sample projects available in the top-X community favored languages, using core language libraries as much as possible(avoid pre-processor helpers, IDE specific plugins, 3rd party libraries, etc...). In those cases where you feel the external helper is beneficial, include a reference implementation of just that library/technology to help the developer learn that skill too.     

Some background: 
My team is comprised of a number of old-timey java developers and student developers.   We are struggling to teach ourselves Spring development in Java to update our skills.    As part of our re-education, we spent nearly a month trying to understand and implement LTI 1.3 into a basic helloworld application, just getting the LTI1.3 to launch our application.  In our case of LTI 1.3, we needed to teach ourselves JWT, learn about and select from 6 different JWT libraries in Java, teach ourselves about the LTI1.3 Launch Flow (OIDC, then Launch), figure out what parameters needed be passed and received at each step through trial and error.   It was tedious having to reinvent already solved problems. In addition, some of Instructure's documentation was buggy, another hurdle.

Instructure could have done a lot to bootstrap otherwise knowledgeable developers with reference implementations of various aspects of Canvas development in common languages.    In our case, if Instructure provided a simple helloworld LTI 1.3 application in Java Spring that did the OIDC and then the Launch in Java, we could have learned from that and been up and running in a day instead of a month.  If Instructure provided a 2nd reference application in Java Spring that shows how to do handoff from LTI Launch to the OAuth flow to get use access_tokens and refresh_tokens, that will save my team another month of research and experimentation.

Another example.   Canvas Data API required to use an obtuse authentication workflow to make API calls, but didn't document well how to actually perform this authentication.    A simple method reference example would have solved this problem for dozens of developers, but instead, the community has come to rely on James Jones Python script to download canvas data files, rather than be equipped with the basic knowledge to do it themselves in their language of choice.    

It does me no good so see all the various NewQuiz endpoints in GraphQL if I don't know how to execute a GraphQL API call in my language of choice .

== Ideas for reference implementations in popular languages.
Make a RESTful API call
Process the JSON Results, inc work with Pagination
Work with SIS IDs
Work with Compound Documents
Work with File Uploads
Make an LTI 1.1 Launch (deprecated...)
Make an OAuth launch, store the refresh_token in memory, request an access_token, make an API call using that token.
Make an LTI 1.3 Launch (OIDC, Launch), inc. working with JWT
Work with Canvas Data Authentication
Load Canvas Data into RDMBS
Work with Canvas Data 2 Authentication
Load Canvas Data 2 into RDMBS
Work with GraphQL
Grade Passback
Live Events

[jwadec]

@glparker I love this feedback and echo everything mentioned. 

To your point, @TamasBalogh, because Instructure has such good documentation for REST api's, I was able to self-teach what I needed to know having never worked with APIs before. I have not found the same wonderful documentation for GraphQL. It is like the wild west. If you all are truly thinking that New Quizzes should be GraphQL first, the documentation and several working examples will need to be provided. Otherwise, I like REST.

GraphQL was implemented similarly to instUI. There was a single post about instUI and then complete silence on further ways developers could implement.

As an aside for other teams at Instructure who have apis: commons, portfolium, canvas studio... there is no consistency/uniformity. Nothing at this point beats the documentation of Canvas Rest APIs.

My takeaway from all of this... don't do this halfheartedly -- go all in so that it can be great. 

[eddie_bonetdiaz]

@jwadec @jsailor @SuSorensen thank you so much for those clarifying points. It actually does satisfy my curiosity behind the topics y'all addressed! Knowing that your teams (or associated teams) intend to add that communication with outcomes before Classic Quizzes gets vaulted is nice. I had not seen it !mentioned in the thread about topics that were being addressed for NQ but I also understand that was a priority list and not a final list.

To @glparker and @glparker although REST would be easier, is it really worth spending time to make the necessary REST changes AND then have to spend more time to translate the code into GraphQL? If we need to learn/change stuff I'd rather start fresh. Although, I have to agree that providing examples would be beneficial to all of us. Instructure wins by providing these examples because then the devs have more time to improve their product instead of spending crucial time in figuring something out that is already known and could be taught to us.

[chriscas]

I definitely agree with the need for more working examples (for either REST or GraphQL)!  I'm a huge learn-by-example person, so even snippets of working code are very helpful.  The REST API pages usually give at least a couple curl command examples to work from.  We definitely need some similar documentation and examples for GraphQL, if it exists.  Perhaps GraphQL is a well known language for some and the documentation isn't needed, but for new/novice users like myself (even being a Computer Science major), the more help you can give the better.

I know Instructure has touted GraphQL for a couple years, but I really haven't seen many people talking about using it for real applications.  Everything I've done myself for internal use has been build using REST APIs, so I really feel like New Quizzes needs to have REST available to fit in with the rest of Canvas.  Developers shouldn't be forced to learn something completely new, with little documentation and examples, just to use New Quizzes.  That would probably further degrade the reputation of New Quizzes throughout the community, which is not desirable at all.

If REST is going to be eventually retired completely, Instructure needs to consider how to support all of the users and developers who rely on it.  Simply saying "convert to GraphQL" isn't going to cut it, in my opinion.  Any transition like that is probably going to need at least 5 years to complete, and even then a lot of things will probably be left broken.  Please try to ensure New Quizzes has feature parity with Classic Quizzes for now, including a full REST API.

-Chris

[bbennett2]

A couple things I'm thinking about re: GraphQL vs REST and what some of the other comments include:

1. Regardless of which method you choose, documentation will make the difference. The REST API documentation is great - it's easy to reference and has good examples of how to make the call, what params to include, etc. The GraphQL "documentation" right now is the explorer which is far less helpful. 

2. Simplicity in GraphQL (a single endpoint accepting JSON payloads) is attractive, but language matters. We do much of our work in Python, which has some GraphQL libraries, but they're not great. REST is still our preferred access method because of stateless requests by different accounts, etc.

3. The web and standards are always evolving and GraphQL is one of those evolutions. Not giving dates for implementation is fine as long as we have sufficient lead time to prepare for breaking changes. As a team of one, I need to prioritize my time pretty carefully and moving our LTI applications to GraphQL will be a significant investment. Please give us more than a couple months to prep.

[dtod]

Just echoing what people are saying about documentation and examples.

[OMIG]

At this stage I don't really mind, I just need something to access submission answers 😓

If you are looking to move everything to GraphQL in the future may as well just do this in GraphQL from the get go!

Any word of a timeline?

[jcacciatore]

A learning mastery gradebook that doesn't talk with one of Canvas's primary assessment tools? How can that even be? 

I'm hoping this gets updated sooner than later. 

[martinvanaken]

Hi! I'm new to Canvas and mostly looking at API side to import as much content as possible into our brand new platforms.

New Quizzes is the part that worries me there - we've a significant number of quizz like questions (mostly "Fill the blank" types) that I'd like to import through some kind of API.

I've followed the discussion here but I'm unclear on the status - is there any way (GraphQL or REST) allowing to retrieve/update/post new New Quizzes/new New Quizzes questions ?

The render and experience is nice, but the encoding would be a pain so we look for "batch like" solutions

Thanks!

[dtod]

New Quizzes worries everyone.

btw for those that haven't seen it, Instructure is committing to GraphQL

[TamasBalogh]

Hi  @glparker  @jwadec, @eddie_bonetdiaz, @chriscas, @bbennett2, 

Thanks for you feedback and I totally agree with you. We need a strong documentation in order to ease the transition. As @dtod mentioned, you should check out Ethan's post about Instructure and GraphQL.

Also please go and review my latest post about the New Quizzes API documentation sample and give your feedback if you have any. Would love to hear your opinions!

@OMIG my next blog post will be about some roadmap-ish information and prioritisation plans.