cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

First steps of New Quizzes API and a sample documentation

TamasBalogh
Instructure
Instructure
6 6 730

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!

6 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 Member

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 Member

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
Instructure

@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 Member

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?