🎓🔥 STARGATE, a gateway for multi models data API 🔥🎓

This intructions will lead you to step by step operations for the workshop on ASTRA + STARGATE for ApiDays Helsinki

Table of content

1. Create Astra Instance
2. Working with Cassandra
3. Working with REST API
4. Working with DOCUMENT API
5. Working with GRAPHQL API

1. Create Astra Instance

ASTRA is the simplest way to run Cassandra with zero operations at all - just push the button and get your cluster. No credit card required, $25.00 USD credit every month, roughly 5M writes, 30M reads, 40GB storage monthly - sufficient to run small production workloads.

✅ Register (if needed) and Sign In to Astra https://astra.datastax.com: You can use your Github, Google accounts or register with an email.

Make sure to chose a password with minimum 8 characters, containing upper and lowercase letters, at least one number and special character

✅ Create a "pay as you go" plan

Follow this guide, to set up a pay as you go database with a free $25 monthly credit.

• Select the pay as you go option: Includes $25 monthly credit - no credit card needed to set up.

You will find below which values to enter for each field.

• For the database name - free_db. While Astra allows you to fill in these fields with values of your own choosing, please follow our recommendations to ensure the application runs properly.

• For the keyspace name - ks1. It's really important that you use the name "free" for the code to work.

You can technically use whatever you want and update the code to reflect the keyspace. This is really to get you on a happy path for the first run.

• For provider and region: Choose and provider (either GCP or AWS). Region is where your database will reside physically (choose one close to you or your users).

• Create the database. Review all the fields to make sure they are as shown, and click the Create Database button.

You will see your new database pending in the Dashboard.

The status will change to Active when the database is ready, this will only take 2-3 minutes. You will also receive an email when it is ready.

2. Working with Cassandra

✅ Check that our keyspace exist

Click your database name, locate the ``CQL Console` TAB and enter this first command:

describe keyspaces;

✅ Create Entities

use ks1;

CREATE TYPE IF NOT EXISTS video_format (
  width   int,
  height  int
);

CREATE TABLE IF NOT EXISTS videos (
 videoid   uuid,
 title     text,
 upload    timestamp,
 email     text,
 url       text,
 tags      set <text>,
 frames    list<int>,
 formats   map <text,frozen<video_format>>,
 PRIMARY KEY (videoid)
);

describe ks1;

✅ Use the data model :

• Insert value using plain CQL

INSERT INTO videos(videoid, email, title, upload, url, tags, frames, formats)
VALUES(uuid(), 'clu@sample.com', 'sample video', 
     toTimeStamp(now()), 'http://google.fr',
     { 'cassandra','accelerate','2020'},
     [ 1, 2, 3, 4], 
     { 'mp4':{width:1,height:1},'ogg':{width:1,height:1}});
     
INSERT INTO videos(videoid, email, title, upload, url)
VALUES(uuid(), 'clu@sample.com', 'video2', toTimeStamp(now()), 'http://google.fr');

• Insert Value using JSON

INSERT INTO videos JSON '{
   "videoid":"e466f561-4ea4-4eb7-8dcc-126e0fbfd573",
     "email":"clunven@sample.com",
     "title":"A Second videos",
     "upload":"2020-02-26 15:09:22 +00:00",
     "url": "http://google.fr",
     "frames": [1,2,3,4],
     "tags":   [ "cassandra","accelerate", "2020"],
     "formats": { 
        "mp4": {"width":1,"height":1},
        "ogg": {"width":1,"height":1}
     }
}';

• Read values

select * from videos;

• Read by id

select * from videos where videoid=e466f561-4ea4-4eb7-8dcc-126e0fbfd573;

🏠 Back to Table of Contents

3. Working with REST API

To use the API we will need a token please create a token following the instructions here:

✅ 3a. Create a token

Follow the documentation to create a token for your app.

Role: Database Administrator

Copy the token value (eg AstraCS:KDfdKeNREyWQvDpDrBqwBsUB:ec80667c....) in your clipboard and save the CSV this value would not be provided afterward.

👁️ Expected output

Now launch the swagger UI

This walkthrough has been realized using the REST API Quick Start. Here we will the the DATA or SwaggerUI

✅ 3b. List keyspaces

• GET: /v2/schemas/keyspaces

• Click Try it out
• Provide your token in the field X-Cassandra-Token
• Click on Execute

✅ 3c. List Tables

• GET /v2/schemas/keyspaces/{keyspaceName}/tables

• Click Try it out
• Provide your token in the field X-Cassandra-Token
• keyspace: ks1
• Click on Execute

✅ 3d. List Types

• GET /v2/schemas/keyspaces/{keyspaceName}/types

• Click Try it out
• X-Cassandra-Token: <your_token>
• keyspace: ks1
• Click on Execute

✅ 3e Create a Table

• POST /v2/schemas/keyspaces/{keyspaceName}/tables

• Click Try it out
• X-Cassandra-Token: <your_token>
• keyspace: ks1
• Data

{
  "name": "users",
  "columnDefinitions":
    [
        {
        "name": "firstname",
        "typeDefinition": "text"
      },
        {
        "name": "lastname",
        "typeDefinition": "text"
      },
      {
        "name": "email",
        "typeDefinition": "text"
      },
        {
        "name": "color",
        "typeDefinition": "text"
      }
    ],
  "primaryKey":
    {
      "partitionKey": ["firstname"],
      "clusteringKey": ["lastname"]
    },
  "tableOptions":
    {
      "defaultTimeToLive": 0,
      "clusteringExpression":
        [{ "column": "lastname", "order": "ASC" }]
    }
}

👁️ Expected output

{
  "name": "users"
}

✅ 3f. Insert Rows

Notice than for the DML you move to DATA. Make sure you are using url with V2, V1 would also work but this is NOT the same payload.

• POST /v2/keyspaces/{keyspaceName}/{tableName}

• X-Cassandra-Token: <your_token>
• keyspaceName: ks1
• tableName: users
• Data

{   
    "firstname": "Cedrick",
    "lastname": "Lunven",
    "email": "c.lunven@gmail.com",
    "color": "blue"
}

You can note that the output code is 201 and return your primary key `{ "firstname": "Cedrick","lastname": "Lunven" }

• You can add a second record changing only the payload

{
    "firstname": "David",
    "lastname": "Gilardi",
    "email": "d.gilardi@gmail.com",
    "color": "blue"
}

• Add a third

{
    "firstname": "Kirsten",
    "lastname": "Hunter",
    "email": "k.hunter@gmail.com",
    "color": "pink"
}

✅ 3g. Read multiple rows

• GET /v2/keyspaces/{keyspaceName}/{tableName}/rows

• X-Cassandra-Token: <your_token>

• keyspaceName: ks1

• tableName: users

• Click Execute

• Notice how now you can only limited return fields

• fields: firstname, lastname

✅ 3h. Read a single partition

• GET /v2/keyspaces/{keyspaceName}/{tableName}/{primaryKey}

• X-Cassandra-Token: <your_token>
• keyspaceName: ks1
• tableName: users
• primaryKey; 'Cedrick`
• Click Execute

- Important: The Swagger user interface is limited as of now and you cannot test a composite key (here adding Lunven). This is a bug in the UI not the API.

✅ 3i. Delete a row

• DELETE /v2/keyspaces/{keyspaceName}/{tableName}/{primaryKey}

• X-Cassandra-Token: <your_token>
• keyspaceName: ks1
• tableName: users
• primaryKey; 'Cedrick`
• Click Execute

✅ 3j. Searches

• GET /v2/keyspaces/{keyspaceName}/{tableName}

• X-Cassandra-Token: <your_token>
• keyspaceName: ks1
• tableName: users
• whereClause; '{"firstname": {"$eq":"David"}}`
• Click Execute

I let you try with {"lastname": {"$eq":"Gilardi"}}.. expected right ?

🏠 Back to Table of Contents

4. Working with DOCUMENT API

This walkthrough has been realized using the Quick Start

locate the Document part in the Swagger UI

✅ 4a. List Namespaces :

• Fill with Header X-Cassandra-Token with <your_token>

👁️ Expected output

{
  "data": [
    { "name": "system_distributed" },
    { "name": "system" },
    { "name": "data_endpoint_auth"},
    { "name": "system_schema"},
    { "name": "ks1" },
    { "name": "stargate_system"},
    { "name": "system_auth" },
    { "name": "system_traces"}
  ]
}

✅ 4b. Create a document :

Note: operations requiring providing namespace and collections on the swagger UI seems not functional. We are switching to CURL the API is working, this is a documentation bug that has been notified to the development team.

• X-Cassandra-Token: <your_token>
• namespaceName: ks1
• collectionname: col1
• Click Execute

{
   "videoid":"e466f561-4ea4-4eb7-8dcc-126e0fbfd573",
     "email":"clunven@sample.com",
     "title":"A Second videos",
     "upload":"2020-02-26 15:09:22 +00:00",
     "url": "http://google.fr",
     "frames": [1,2,3,4],
     "tags":   [ "cassandra","accelerate", "2020"],
     "formats": { 
        "mp4": {"width":1,"height":1},
        "ogg": {"width":1,"height":1}
     }
}

👁️ Expected output:

{
  "documentId":"<your_document_id>"
}

✅ 4c. Retrieve documents :

• X-Cassandra-Token: <your_token>
• namespaceName: ks1
• collectionname: col1
• Click Execute

✅ 4d. Retrieve 1 document :

• X-Cassandra-Token: <your_token>
• namespaceName: ks1
• collectionname: col1
• documentId: <your_document_id>
• Click Execute

✅ 4e. Search for document by properties :

• X-Cassandra-Token: <your_token>
• namespaceName: ks1
• collectionname: col1
• documentId: <your_document_id>
• WhereClause

{"email": {"$eq": "clunven@sample.com"}}

🏠 Back to Table of Contents

5. Working with GRAPHQL API

This walkthrough has been realized using the GraphQL Quick Start

✅ Open GraphQL Playground :

Open the playground

👁️ Expected output

✅ Creating a keyspace :

Before you can start using the GraphQL API, you must first create a Cassandra keyspace and at least one table in your database. If you are connecting to a Cassandra database with existing schema, you can skip this step.

Then provide the keyspace name library:

✅ Creating a Table :

• Use this query

mutation {
  books: createTable(
    keyspaceName:"library",
    tableName:"books",
    partitionKeys: [ # The keys required to access your data
      { name: "title", type: {basic: TEXT} }
    ]
    values: [ # The values associated with the keys
      { name: "author", type: {basic: TEXT} }
    ]
  )
  authors: createTable(
    keyspaceName:"library",
    tableName:"authors",
    partitionKeys: [
      { name: "name", type: {basic: TEXT} }
    ]
    clusteringKeys: [ # Secondary key used to access values within the partition
      { name: "title", type: {basic: TEXT}, order: "ASC" }
    ]
  )
}

👁️ Expected output

✅ Populating Table :

Any of the created APIs can be used to interact with the GraphQL data, to write or read data.

First, let’s navigate to your new keyspace library inside the playground. Change tab to graphql and pick url /graphql/library.

• Use this query

mutation insert2Books {
  moby: insertbooks(value: {title:"Moby Dick", author:"Herman Melville"}) {
    value {
      title
    }
  }
  catch22: insertbooks(value: {title:"Catch-22", author:"Joseph Heller"}) {
    value {
      title
    }
  }
}

• Don't forget to update the header again

{
  "x-cassandra-token":"7c37bda5-7360-4d39-96bc-9765db5773bc"
}

👁️ Expected output

✅ Read data :

Stay on the same screen and sinmply update the query with

query oneBook {
    books (value: {title:"Moby Dick"}) {
      values {
        title
        author
      }
    }
}

👁️ Expected output

🏠 Back to Table of Contents

THE END

Congratulation your made it to the END.