GraphQL Queries with National Cancer Institute’s GDC GraphQL

A Little Bit About The REST Architectural Style

Before we go into GraphQL queries, we may want to mention some things about REST APIs we may not know or may have forgot. REST or Representational State Transfer is an architectural style we generally attribute to Roy Fielding. I know calling REST an architectural style can be confusing because generally when we think about architectural styles, we think about people like Frank Lloyd Wright. 

If you stretch your mind far enough, you can see how traditional architecture concepts could be applied by late 20th century software engineers to software architecture. In his well-known dissertation on REST, Fielding defined an architectural style as:

“a coordinated set of architectural constraints that restricts the roles/features of architectural elements and the allowed relationships among those elements within any architecture that conforms to that style”

GraphQL Queries

After validation, a GraphQL query is executed by a GraphQL server which returns a result mirroring the shape of the requested query, typically as JSON. Ignoring subscriptions for the moment, the two primary operations are queries and mutations. 

Simply put, queries fetch data and mutations change data. It may take some time to get used to this. With REST APIs, you are used to fetching data from multiple endpoints, whereas, with GraphQL APIs, you’re typically going to be fetching data from just one. Nor do you have to concern yourself with HTTP methods. You only have to know whether the operation is a query or a mutation.

I should mention REST API calls and GraphQL calls are both HTTP requests. It’s much easier to use a GraphQL tool, but it is possible to do a GraphQL API call with curl. I know many refer to GraphQL APIs as an alternative to REST APIs. I prefer to think of them as an extension.   

If you’re looking for a GraphQL schema to get started with, the National Cancer Institute has a good one they call the GDC GraphQL Schema. As of this writing, GDC GraphQL has two endpoints:

• GDC Search and Retrieval Endpoint: https://api.gdc.cancer.gov/v0/graphql
• Submission Endpoint: https://api.gdc.cancer.gov/v0/submission/graphql

You May Also Like

• Restful APIs Are Good, But GraphQL APIs Are Usually Better
• Honoring the Life and Work of Chadwick Boseman
• Learning GraphQL: Declarative Data Fetching for Modern Web Apps

References

1. Execution | GraphQL. https://graphql.org/learn/execution/. Accessed 9 May 2021.
2. What is a GraphQL query? https://www.apollographql.com/blog/what-is-a-graphql-query-graphql-query-examples-using-apollo-explorer/. Accessed 9 May 2021.
3. GraphQL Examples – GDC Docs. https://docs.gdc.cancer.gov/API/Users_Guide/GraphQL_Examples/. Accessed 9 May 2021.
4. Fielding, Roy T. Architectural styles and the design of network-based software architectures. Vol. 7. Irvine: University of California, Irvine, 2000.