{{announcement.body}}
{{announcement.title}}

DataStax Astra GraphQL/REST API Services

DZone 's Guide to

DataStax Astra GraphQL/REST API Services

An introduction to the Astra GraphQL and REST API Services.

· Database Zone ·
Free Resource

With Astra, if you've used Apache Cassandra or DataStax Enterprise you can use the same drivers or CQL you're familiar with. But with Astra, there are two additional capabilities we've just released to use in connecting to and working with your databases:

  • Astra REST API
  • Astra GraphQL API

With the REST API there are a number of capabilities to add a table, return a list of all the tables, return content of a table, and delete a table. In addition to tables, there is functionality to retrieve, retrieve all, add, update, and delete columns. All of the standard CRUD (Create, Read, Update, and Delete) commands can also be performed.

For the GraphQL API it gives you the ability to perform CRUD actions and query with filters using the GraphQL syntax.

Authorization Token

To use either of these services, the first thing you'll need is to create one of Astra's time-based authorization tokens. These tokens work until 30 minutes after the last call made with the token. Once expired a new token must be created. To create a token an HTTP POST to the API can be made, passing several header values, and username and password in the body of a POST request.

For an example of retrieving an authorization token I've put together a cURL request below. To get the URL for your database navigate to the Astra dashboard, and on the summary screen of any database the API Access URL's are listed.

C
 







A successful request will return a result with the auth token that looks like this.

Java
 




xxxxxxxxxx
1


 
1
{"authToken":"9a38437f-7e03-49a8-bc5d-b4e305d7c1e8"}



With that authorization token we can now call actions against the REST, or GraphQL API's.

Creating a Table via the Astra REST API

To create a table, we need a few key elements: The table name, whether it should create if a table exists or not, and column definitions with at least one column as a primary key. This is done by using JSON to pass this schema to the REST API. Here's an example of some JSON that can be used to create a table.

JSON
 







To use this JSON to create a table, just add the pertinent headers, insert your keyspace into the URL, and the x-cassandra-token and POST this data to the REST API end point. A cURL request to create the table would look like this.

C
 







Adding Data via a GraphQL Mutation

At this point, with a data created, we can add, update, or delete data. The sample curl statement I've put together here is a sample GraphQL mutation to add a record to the products table.

C
 




xxxxxxxxxx
1


 
1
curl --request POST \
2
  --url https://ba965c97-86f1-4d38-8cne-58qa1d2209a1-us-east1.apps.astra.datastax.com/api/rest/v1/keyspaces/betterbotz/tables/orders/rows \
3
  --header 'accept: application/json' \
4
  --header 'content-type: application/json' \
5
  --header 'x-cassandra-request-id: xyzaa27b-de8e-4afc-8431-8f06a326047d' \
6
  --header 'x-cassandra-token: 3ad1ca6a-62pq-4e1b-b273-4c08ea334909' \
7
  --data-raw '{"query":"mutation {superarms: insertProducts(value:{id:\"65cad0df-4fc8-42df-90e5-4effcd221ef7\"\n name:\"Arm Spec A1\" description:\"Powerful Robot Arm Spec A.\"price: \"9999.99\" created: \"2012-04-23T18:25:43.511Z\"}){value {name description price created}}}","variables":{}}'



For some other examples issuing a GraphQL mutation to add a record, just for good measure.

Go

Go
 




xxxxxxxxxx
1
34


 
1
package main
2
 
          
3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io/ioutil"
8
)
9
 
          
10
func main() {
11
 
          
12
  url := "https://32c3bb24-e2df-4db3-b993-14707303e57c-us-east1.apps.astra.datastax.com/api/graphql"
13
  method := "POST"
14
 
          
15
  payload := strings.NewReader("{\"query\":\"mutation {superarms: updateProducts(value: {id:\\\"65cad0df-4fc8-42df-90e5-4effcd221ef7\\\" name:\\\"Arm Spec A3 [Newly Updated]\\\" description:\\\"Powerful Robot Arm Spec A3.\\\" price: \\\"19999.99\\\" created: \\\"2012-04-23T18:25:43.511Z\\\" }){value {id name description price created}}}\",\"variables\":{}}")
16
 
          
17
  client := &http.Client {
18
  }
19
  req, err := http.NewRequest(method, url, payload)
20
 
          
21
  if err != nil {
22
    fmt.Println(err)
23
  }
24
  req.Header.Add("accept", "*/*")
25
  req.Header.Add("content-type", "application/json")
26
  req.Header.Add("X-Cassandra-Token", "e85b3021-fb89-4f43-9ba6-a64a49ba5f68")
27
  req.Header.Add("Content-Type", "application/json")
28
 
          
29
  res, err := client.Do(req)
30
  defer res.Body.Close()
31
  body, err := ioutil.ReadAll(res.Body)
32
 
          
33
  fmt.Println(string(body))
34
}



Python

Python
 




xxxxxxxxxx
1
15


 
1
import requests
2
 
          
3
url = "https://32c3bb24-e2df-4db3-b993-14707303e57c-us-east1.apps.astra.datastax.com/api/graphql"
4
 
          
5
payload = "{\"query\":\"mutation {superarms: updateProducts(value: {id:\\\"65cad0df-4fc8-42df-90e5-4effcd221ef7\\\" name:\\\"Arm Spec A3 [Newly Updated]\\\" description:\\\"Powerful Robot Arm Spec A3.\\\" price: \\\"19999.99\\\" created: \\\"2012-04-23T18:25:43.511Z\\\" }){value {id name description price created}}}\",\"variables\":{}}"
6
headers = {
7
  'accept': '*/*',
8
  'content-type': 'application/json',
9
  'X-Cassandra-Token': 'e85b3021-fb89-4f43-9ba6-a64a49ba5f68',
10
  'Content-Type': 'application/json'
11
}
12
 
          
13
response = requests.request("POST", url, headers=headers, data = payload)
14
 
          
15
print(response.text.encode('utf8'))



Java

Java
 




xxxxxxxxxx
1
13


 
1
OkHttpClient client = new OkHttpClient().newBuilder()
2
  .build();
3
MediaType mediaType = MediaType.parse("application/json");
4
RequestBody body = RequestBody.create(mediaType, "{\"query\":\"mutation {superarms: updateProducts(value: {id:\\\"65cad0df-4fc8-42df-90e5-4effcd221ef7\\\" name:\\\"Arm Spec A3 [Newly Updated]\\\" description:\\\"Powerful Robot Arm Spec A3.\\\" price: \\\"19999.99\\\" created: \\\"2012-04-23T18:25:43.511Z\\\" }){value {id name description price created}}}\",\"variables\":{}}");
5
Request request = new Request.Builder()
6
  .url("https://32c3bb24-e2df-4db3-b993-14707303e57c-us-east1.apps.astra.datastax.com/api/graphql")
7
  .method("POST", body)
8
  .addHeader("accept", "*/*")
9
  .addHeader("content-type", "application/json")
10
  .addHeader("X-Cassandra-Token", "e85b3021-fb89-4f43-9ba6-a64a49ba5f68")
11
  .addHeader("Content-Type", "application/json")
12
  .build();
13
Response response = client.newCall(request).execute();



and C#!

C#
 




xxxxxxxxxx
1
11


 
1
var client = new RestClient("https://32c3bb24-e2df-4db3-b993-14707303e57c-us-east1.apps.astra.datastax.com/api/graphql");
2
client.Timeout = -1;
3
var request = new RestRequest(Method.POST);
4
request.AddHeader("accept", "*/*");
5
request.AddHeader("content-type", "application/json");
6
request.AddHeader("X-Cassandra-Token", "e85b3021-fb89-4f43-9ba6-a64a49ba5f68");
7
request.AddHeader("Content-Type", "application/json");
8
request.AddParameter("application/json", "{\"query\":\"mutation {superarms: updateProducts(value: {id:\\\"65cad0df-4fc8-42df-90e5-4effcd221ef7\\\" name:\\\"Arm Spec A3 [Newly Updated]\\\" description:\\\"Powerful Robot Arm Spec A3.\\\" price: \\\"19999.99\\\" created: \\\"2012-04-23T18:25:43.511Z\\\" }){value {id name description price created}}}\",\"variables\":{}}",
9
           ParameterType.RequestBody);
10
IRestResponse response = client.Execute(request);
11
Console.WriteLine(response.Content);



Feel free to ping me on Twitter @Adron or here in comments, I'm open to and would love to discuss your experience!

Topics:
csharp ,database ,dbaas ,distributed database ,graphql api ,java ,javascript ,programming ,rest api ,tutorial

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}