First steps of New Quizzes API and a sample documentation

This blog from the Instructure Product Team is no longer considered current. While the resource still provides value to the product development timeline, it is available only as a historical reference.

TamasBalogh
Instructure Alumni
Instructure Alumni
20
6516

GraphQL vs REST decision

Last time we were curious about your preferences for GraphQL or REST. We wanted to understand how you leverage the current Quiz API and for what purposes. You gave us great insights into what you are doing, how you are doing and what you desire from a New Quizzes API.

You may have already read Ethan’s post about Instructure’s commitment to GraphQL as a long term strategy. Given that direction, we believe the logical step is to implement New Quizzes API in GraphQL now. Inevitably you will need to change your integrations and scripts related to quizzes to use New Quizzes, since having the exact same API endpoints and behaviour for New Quizzes (as Classic Quizzes) is just not possible. Obviously changing code to handle GraphQL API is a bigger challenge for you than just modifying it for new REST endpoints. We kept in mind that sooner or later GraphQL will take place across Canvas and you would need to rewrite your code all over again. Most importantly, your feedback indicates pain points which would be resolved best with GraphQL. Concern that we have heard is mostly about the need for clear documentation. This post provides an overview and examples for your consideration.

How this will affect you

Reaching the GraphQL API is quite simple. After you authenticated to your regular REST API you need to request an instaccess token and with that you simply connect to the GraphQL and start making queries and mutations. Those will retrieve JSON objects which should be already familiar to you if you ever used our APIs.

GraphQL is all about use cases and our approach is to build the API iteratively, adding the minimal set of use cases and fields first and build from there. Don’t worry if you can’t find a way to implement your use case or you can’t see an important field to a related object, this post is exploratory. You can always raise your voice and we will investigate priority for implementation. 

An example

Please note that the following example is just a draft and it is completely in an experimental phase. The queries/mutations and the object itself can and most likely will change before the release and lots of fields are missing now for the sake of simplicity. I just would like to show you what you can expect from us with New Quizzes GraphQL API documentation.

Take a look at the QuizQuestion object. In the REST world, you could create, update, delete and get one single question or list all the questions to a quiz. You can check out the Classic Quiz QuizQuestion API endpoints and the current documentation here.

In New Quizzes, we introduced a new kind of quiz content named Stimulus which ​​gives students a piece of content with associated questions. So a quiz can consist of a list of questions and/or stimuli which can also include more questions. I know this complicates things, especially from the API point of view, since these two are quite similar but still different. Both of them are in the same list in a quiz or an Item Bank. Let’s call them QuizItem and go through the QuizItem GraphQL interface and some mutations regarding it. 

Documentation for QuizItem

Screenshot 2021-09-13 at 17.13.10.png

 

Screenshot 2021-09-13 at 17.20.58.pngScreenshot 2021-09-13 at 17.21.11.png

 

 If you would click on QuizQuestion you would be navigated to another page:

Screenshot 2021-09-13 at 17.23.37.png

 

Screenshot 2021-09-13 at 17.23.57.png

 

The QuizItemCreate link would navigate you to here:

Screenshot 2021-09-13 at 17.25.17.png

I think this is enough to imagine the rest, like a sample call for a mutation and other input objects but I wouldn’t spam you with more screenshots for now.

We value your feedback

We try to build an API our customers love to use and handle as many use cases as possible without overcomplicating the schema, but we may miss something obvious. How do you feel about the QuizItem object so far? Is a documentation detailed like this useful or you would need additional help? I encourage you to add any feedback, concerns or suggestions in the comments!

This blog from the Instructure Product Team is no longer considered current. While the resource still provides value to the product development timeline, it is available only as a historical reference.

20 Comments
RobDitto
Community Champion

I'm so happy to learn about the plans for GraphQL API documentation! 

Even though I'm more of an advocate for our in-house developers and external suppliers, rather than a hands-on coder, I believe that most of our success stories to date with Canvas APIs have had documentation as their foundation. It will be great to have GraphQL APIs included in that strong foundation.

MattHanes
Community Champion

Thanks for the update, @TamasBalogh ! I'm definitely going to need more help because I don't know GraphQL at all but I was very comfortable with the REST API. I have some advice on how to promote this change:

  1. I think the biggest help would be to provide some curated real-world examples of how to use the endpoints. Allow the community to contribute to the curated list as well. 

  2. Have a developer post a weekly video in which they solve a problem or create a useful query that is added to the list mentioned above. Bonus points for using different programming languages to appeal to a larger userbase. I mostly only use Python myself, but I know there are folks using C#, Javascript, Ruby, etc...

  3. Folks may be a bit salty about having to learn GraphQL, so when making the real-world examples, try to highlight the instances in which the GraphQL approach is superior to the REST API. After reading Ethan's post, I felt a lot better about having to learn GraphQL knowing how much can be done to retrieve information that would ordinarily have required multiple requests through the API. 

Thanks again for your work on this!

ross_bell
Community Explorer

Speaking only for myself it would be most helpful to have a crosswalk table of the REST API endpoints to GraphQL endpoints (as they become available).  To make it incredibly helpful include links to documentation and examples in table.

Thanks

BryanHenderson
Community Novice

Linking field types will be very helpful.  For instance, both your quizItem interface and quizQuestion object show that they have a 'bank (QuizBank)' field, but there is no link anywhere to define what a QuizBank is and the fields it contains.  A link to this type may be available in some global list/catalog somewhere else, but it would be very helpful if, when defining a field and its type, that if the type is not a base type (like int, or string) that it becomes a link to the definition of that type.

TamasBalogh
Instructure Alumni
Instructure Alumni

@MattHanes Thanks for pointing out your thoughts. As we implement the API I plan to upload posts about real life examples and more helping guides, but for now it's unclear how and in what format I should help. 

@ross_bell Unfortunately, the way GraphQL works (versus REST endpoints) and the difference between Classic Quizzes and New Quizzes makes this impossible and irrelevant. So adding this kind of mapping to the documentation cannot be done, but you gave me a good idea to add an additional resource explaining some of the use cases in both technology and the difference and similarities.

@BryanHenderson Absolutely! There will be links to these types definitely. I was just struggling with the formatting 🙂 

marcia_moraes
Community Explorer

Thank you for the example.

I am sorry, I could not find this information in the previous blogs regarding REST API x GraphQL API, is there a timeline for when the GraphQL API documentation is going to be available for the community to start working on migrating their REST API applications?

ross_bell
Community Explorer

@TamasBalogh 

Since a direct mapping between the two APIs cannot be done, how about a table that maps the return payload of existing endpoints to a GraphQL example?  For instance the QuizSubmission object, what will the GraphQL query for the equivalent data look like?

 

 

TamasBalogh
Instructure Alumni
Instructure Alumni

Hi @marcia_moraes, I am currently working on a roadmap regarding the API, but as always, we won't be able to commit to deadlines in advance. The documentation will be released alongside the API itself.

 

@ross_bell Yes, something similar was my thought. Please stay tuned for my upcoming posts. 

TamasBalogh
Instructure Alumni
Instructure Alumni

Hello everybody,

Please fill out this short survey about your priorities on use cases regarding New Quizzes tooling (external or developed by your institution). It would help me understand which use cases (and related API functions) are the most important and pressing.

candrew
Community Participant

One of the key pieces missing from New Quizzes is the ability to get a raw data export of the answers by student and/or the student analysis (either via a CSV/Excel export or API call).  This makes re-grades especially difficult to verify when it comes to auditing (especially when there seems to be a systemic discrepancy between the quiz result report and the gradebook after there has been a regrade.  When I say systemic, it only affects a particular quiz (that I'm aware of).  It has frustrated myself and in particular a  disgruntled faculty member and I don't have a universal way to export the raw data to run my own analysis (like I could with the classic quizzes api).

Also, running the item analysis took almost 24 hours to run for a 46 question MCQ exam which is disappointing given that the New Quizzes product is over 3 years at this point with plans near enough to deprecate classic quizzes.

TamasBalogh
Instructure Alumni
Instructure Alumni

Hi @candrew 

Thanks for pointing this out. We are currently investigating and prioritizing the option to get raw submission data via API to enable customers to have custom analysis.

AlanaDore
Community Novice

Will we be able to support New Quizzes and the existing Quizzes via one API since People can use both quiz options within a single course?  

TamasBalogh
Instructure Alumni
Instructure Alumni

@AlanaDore Unfortunately no. Supporting that would be a huge amount of work and maybe even impossible since the two quiz engine are not the same.

GregoryMyers
Community Member

Having looked into GraphQL, this looks like a solution in search of a problem.  The existing REST API is well documented and already is not used to its full potential (i.e. content creator automation), so injecting another technology is only going to discourage independent instructors from leveraging the new API.  

candrew
Community Participant

@TamasBalogh Has there been any update in regards to data export via api (or even better...by UI and CSV/Excel Export to make this usable directly by faculty members).  This has certainly been mentioned in other forums as one of the reasons why NOT to adopt New Quizzes?  Thank you

kaitlinhatfield
Community Member

How would you authenticate using these requests? I'm trying to use this API to get a quiz's questions but I'm getting authentication errors.

TamasBalogh
Instructure Alumni
Instructure Alumni

@candrew Quiz details and quiz questions will be retrievable via API when Iteration 1 will be released.

TamasBalogh
Instructure Alumni
Instructure Alumni

@kaitlinhatfield This is just a preview how the Quiz API and the documentation will look like. It's not in production yet.

kaitlinhatfield
Community Member

@TamasBalogh  then how do i get new quiz questions from an API?

TamasBalogh
Instructure Alumni
Instructure Alumni

@kaitlinhatfield Unfortunately, right now you can't do that. You'll be able to once the first iteration of New Quizzes API is released. You may subscribe to the New Quizzes Hub to get regular updates.