graphQL documentation

Jump to solution
ben_reed
Community Explorer

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

Labels (1)
0 Likes
1 Solution
James
Community Champion

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

View solution in original post