In this blog, we will introduce and explore DataStax Astra’s GraphQL API. Also, a video is embedded in the blog where you can watch a live demo where we use Postman to make GraphQL queries and mutations to our Astra database.
If you have been following us here at Anant, then you know that we have already worked with DataStax Astra and created an open source application that you can use to quickly try Astra out. The repo can be found here: https://github.com/Anant/cassandra.api. Also, you can check out some blogs and webinars that we have done in conjunction with this repo and DataStax Astra below.
- Cassandra.API Documentation Walkthrough
- Cassandra.API Blog Post: Part 1
- Cassandra.API Blog Post: Part 2
- Building a REST API with DataStax Astra using Node & Python: Part 1
- Building a REST API with DataStax Astra using Node & Python: Part 2
- Cassandra.API Live Workshop w/DataStax
- Cassandra.API Video Demo: Part 1
- Cassandra.API Video demo: Part 2
- Cassandra as a Service in the Cloud
For Cassandra.API, we used the Python and Node.js drivers to connect to Astra, and for Exploring DataStax Astra’s REST API, we used Astra’s REST API to build a simple CRUD app with React on Gitpod. And now, we finally take a look at DataStax Astra’s GraphQL API.
GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data. GraphQL was developed internally by Facebook in 2012 before being publicly released in 2015.
While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request. GraphQL queries always return predictable results and apps using GraphQL are fast and stable because they control the data they get, not the server.
Many different programming languages support GraphQL. This list contains some of the more popular server-side frameworks, client libraries, services, and other useful stuff.
The DataStax Astra GraphQL API allows you to easily interact with your data using GraphQL types, queries, and mutations. For every table in your keyspace, a series of GraphQL objects are generated, along with queries and mutations that allow you to search and modify the table data. So unlike the REST API, where you can CRUD tables, rows, and columns, the GraphQL API only allows for CRUD of rows. You will still need the REST API when using the GraphQL API because the authorization endpoint is https://{databaseId}-{region}.apps.astra.datastax.com/api/rest/v1/auth.
The endpoint for the GraphQL API is https://{databaseid}-{region}.apps.astra.datastax.com/api/graphql. The default naming convention for the GraphQL API converts CQL table and column names to lowerCamelCase for GraphQL fields and UpperCamelCase for GraphQL types.
Here is an example of a dummy Astra table that DataStax’s Docs provides, which shows the schema, fields, and types generated for your Astra table.
schema {
query: Query
mutation: Mutation
}
type Query {
products(value: ProductsInput, orderBy: [ProductsOrder], options: QueryOptions): ProductsResult
productsFilter(filter: ProductsFilterInput!, orderBy: [ProductsOrder], options: QueryOptions): ProductsResult
}
type Mutation {
insertProducts(value: ProductsInput!, ifNotExists: Boolean, options: UpdateOptions): ProductsMutationResult
updateProducts(value: ProductsInput!, ifExists: Boolean, ifCondition: ProductsFilterInput, options: UpdateOptions): ProductsMutationResult
deleteProducts(value: ProductsInput!, ifExists: Boolean, ifCondition: ProductsFilterInput, options: UpdateOptions): ProductsMutationResult
}
The query types that are generated include:
products(): Query product values by equality. If no value argument is provided then the first 100 (default pagesize) values are returned.productsFilter: Query products values by filtering the result with additional operators. For examplegt(greater than),lt(less than),in(in a list of values). Theproducts()equality style query is preferable if your queries don’t require non-equality operators.
The generated mutations include:
insertProducts(): Insert a new product. This is an “upsert” operation that will update the value of existing products if they already exists unlessifNotExistsis set to true. UsingifNotExistscauses the mutation to use a lightweight transaction (LWT) adding significant overhead to the query.updateProducts(): Update an existing product. This is also an “upsert” and will create a new product if one doesn’t exists unlessifExistsis set to true. UsingifExistsorifConditioncauses the mutation to use a lightweight transaction (LWT) adding significant overhead to the query.deleteProducts(): Deletes a product. UsingifExistsorifConditioncauses the mutation to use a lightweight transaction (LWT) adding significant overhead to the query.
For more information, you can see DataStax Astra’s GraphQL API documentation here. Unfortunately, there is no documentation on doing bulk inserts/multi-row additions using the insertTableName mutation, so I am not entirely sure if that is not allowed through the API, or it just has not been documented.
If you want a video form of the instructions for using Postman below, a video is embedded further down the blog. Don’t forget to like and subscribe while you are there!
If you want to try out this GraphQL API quickly, here is a Postman template collection that you can use to try it out. To use this collection, you first need to create an Astra account/database. Once you have a database, you can download this DataStax Studio notebook. Then, you can drag and drop the notebook into your Astra instance of DataStax Studio and run the 3 cells to create the table, seed a record, and confirm the record exists.
Then, we can move onto using Postman and the GraphQL API. Once the Postman collection is imported into Postman, we will open the first request: Authorization. This request makes a POST request to the REST API to get our auth token. Once the request is open, you will need to insert your API URL from the connect page of your database. As I mentioned above, the REST API is required for authorization, so you can copy either the REST API URL or the GraphQL API URL up to /api. Then paste that into the URL section on Postman and then open the Body tab to insert your database credentials into the request body object. Once done, hit send and copy the value of the returned token.
Now, we can query our Astra database with GraphQL. Open the GraphQL Query request, and insert the copied token value into the x-cassandra-token key-value pair under the Headers tab. Then again, copy and paste the API URL up until /api in the URL just before /graphql. Then, if we open the Body tab, we can see the query I have already made for you. You can hit send and see the response in realtime. You can then play with the query to return exactly what you need, as that is the benefit of using GraphQL as mentioned above. You can follow these set-up steps: copy and paste token into Headers and copy and paste the API URL into the request URL, for the rest of the queries, which are the mutations: Add Row using GraphQL, Update Row using GraphQL, and Delete Row using GraphQL.
Again, as mentioned before the instructions, if you want to watch how you can test DataStax Astra’s GraphQL API with Postman in a live demo, you can watch the video embedded below. Also, in the video, we go into some nuances that may trip someone up when writing the Astra GraphQL queries. Once you watch the video, don’t forget to like and subscribe!
Additionally, if you want to create a front-end Javascript app that uses GraphQL and utilizes DataStax Astra’s GraphQL API, you can check out Gatsby + gatsby-source-graphql plugin; as well as, React + Apollo GraphQL -> Apollo React Client. Apollo GraphQL has other Javascript frameworks it can work with so you can try with Angular, Vue, or Ember as well.
Cassandra.Link
Cassandra.Link is a knowledge base that we created for all things Apache Cassandra. Our goal with Cassandra.Link was to not only fill the gap of Planet Cassandra, but to bring the Cassandra community together. Feel free to reach out if you wish to collaborate with us on this project in any capacity.
We are a technology company that specializes in building business platforms. If you have any questions about the tools discussed in this post or about any of our services, feel free to send us an email!
