graphQL documentation

[ben_reed]

i have found the REST documentation to be quite good, but i haven't found graphQL documentation. it's nice that graphql schema is discoverable, but i'm left with some questions. here are two that i'm struggling with:

1) assigment.submissionsConnection.nodes has both an attachment and attachments field. why both? is there a case when i use one rather than the other?

2) many structures, such as submissionsConnects has a nodes field and an edges field with a node member. how are those two fields related? is there a reason to use one over the other?

in general, i love the move to graphQL, i think it is the right one. there just needs to be a bit more documentation on the more subtle details of how instructure is using it.

thank you,

ben

[James · Accepted solution]

@ben_reed 

According to the source code, attachment is a singular object while attachments is an array of objects. The first calls load_association() while the second calls load_many().

I am not an expert on GraphQL, so if I get this wrong, someone please correct me.

nodes vs edges is a GraphQL design issue. This page on GraphQL pagination attempts to explain. The edges will include a cursor, which can be used in pagination. Otherwise, the data is the same. If you're not using pagination, then you can use the nodes. If you are using pagination, then you can use edges. I say can use edges because you can also do pagination without using edges by using pageInfo.

The layout of the information is different as well. If you're using edges, then edges is an array of objects that have a node property with the information and a cursor property. If you're using nodes, then nodes is an array of objects with the information you requested but no cursor information.

When I have been forced to use GraphQL, I have gone with the pageInfo route to pagination. I'm trying to fetch all of the information, but sometimes there is so much information that it times out so I have to use pagination to get the data. My initial query uses first in the connection. Then I use the endCursor and hasNextPage properties to decide whether to continue fetching more information. When there is additional data to load, I take the endCursor and use it as the after property in the connection line.

I'm trying to think of why you would want to do edges over just nodes. One thing I can think of is if you had a process that took one query and then gathered additional information about each object, but the process may fail. You want the ability to pick back up where you left off without going through everything again and so you use edges and save the cursor that was last processed. Using edges somewhat reduces the need for pageInfo, except that you won't know when you've consumed all of the data without the pageInfo.hasNextPage property. Still, I've seen some programmers advocating that kind of pagination with the REST API (just keep incrementing the page query parameter until it fails, ignoring the link headers), but I cannot recommend that approach.

[ben_reed]

great explanation about edges vs nodes! i should have noticed the cursor.

as far as attachments, i can't quite follow the code to understand when an attachment would be filled in and which attachments would. it appears in my data that everything is under attachments.

[James]

@ben_reed 

I don't read Ruby either, so from that code, I couldn't tell what the difference was. My file upload online submission attachments are showing up under the plural as well.

Maybe it has to do with the type of assignment where the submission was made. File upload for online online submissions allow for multiple attachments so it would show up under attachments, even if there was only one. Perhaps some type (maybe external tools?) only allow a single attachment.

[RobDitto]

Comprehensive documentation for the GraphQL API is under development, according to:

• First steps of New Quizzes API and a sample documentation 

[themidiman]

I know this already is solved, but wanted to point out that I'm trying to keep my previous use of the REST API and see how it can be transitioned to GraphQL as Instructure continues getting its transition moving forward.

If you have a linked-in learning account, you might try taking this course.

It's making my efforts to poke around in the interactive <instance>.instructure.com/graphiql browser playground feel more productive. It was mostly guesswork up until now.

I'm looking forward to transitioning some of my automated projects to the GraphQL mode of thinking after finishing the above course and others like it.