{"id":27370239,"url":"https://github.com/datastaxdevs/conf-grpc-rest-graphql-data-apis","last_synced_at":"2025-04-13T08:48:31.652Z","repository":{"id":49797397,"uuid":"428680063","full_name":"datastaxdevs/conf-grpc-rest-graphql-data-apis","owner":"datastaxdevs","description":"Expose Rest,Graphql,Grpc Apis on Top for Your Databases","archived":false,"fork":false,"pushed_at":"2022-12-13T13:21:56.000Z","size":8954,"stargazers_count":3,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2023-03-04T04:05:47.311Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datastaxdevs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-16T14:06:52.000Z","updated_at":"2023-01-19T17:26:27.000Z","dependencies_parsed_at":"2023-01-28T12:31:27.083Z","dependency_job_id":null,"html_url":"https://github.com/datastaxdevs/conf-grpc-rest-graphql-data-apis","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastaxdevs%2Fconf-grpc-rest-graphql-data-apis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastaxdevs%2Fconf-grpc-rest-graphql-data-apis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastaxdevs%2Fconf-grpc-rest-graphql-data-apis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastaxdevs%2Fconf-grpc-rest-graphql-data-apis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastaxdevs","download_url":"https://codeload.github.com/datastaxdevs/conf-grpc-rest-graphql-data-apis/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248688196,"owners_count":21145762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-13T08:48:30.959Z","updated_at":"2025-04-13T08:48:31.644Z","avatar_url":"https://github.com/datastaxdevs.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## 🎓🔥 Expose Rest, Graphql, Grpc Data Apis for Your Databases 🔥🎓\n\n[![License Apache2](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n[![Discord](https://img.shields.io/discord/685554030159593522)](https://discord.com/widget?id=685554030159593522\u0026theme=dark)\n\nThis instructions will lead you to step by step operations for the talks at DeveloperWeek Austin\n\n## Table of content\n\n1. [Show me some Api Code](https://github.com/datastaxdevs/conference-2021-developer-week-austin/tree/main/sample-code)\n2. [Show me Docker File](https://github.com/datastaxdevs/conference-2021-developer-week-austin/blob/main/sample-docker/docker-compose.yml)\n3. [Show me the SLIDES](https://github.com/datastaxdevs/conference-2021-developer-week-austin/blob/main/slides.pdf)\n3. [Create Astra Instance](#1-create-astra-instance)\n4. [Working with Cassandra](#2-working-with-cassandra)\n5. [Working with REST API](#3-working-with-rest-api)\n6. [Working with DOCUMENT API](#4-working-with-document-api)\n7. [Working with GRAPHQL API](#5-working-with-graphql-api)\n\n## 1. Create Astra Instance\n\n**`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.  \n\n✅ Register (if needed) and Sign In to Astra [https://astra.datastax.com](https://dtsx.io/workshop): You can use your `Github`, `Google` accounts or register with an `email`.\n\n_Make sure to chose a password with minimum 8 characters, containing upper and lowercase letters, at least one number and special character_\n\n✅ Create a \"pay as you go\" plan\n\nFollow this [guide](https://docs.datastax.com/en/astra/docs/creating-your-astra-database.html), to set up a pay as you go database with a free $25 monthly credit.\n\n- **Select the pay as you go option**: Includes $25 monthly credit - no credit card needed to set up.\n\nYou will find below which values to enter for each field.\n\n- **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.\n\n- **For the keyspace name** - `ks1`. It's really important that you use the name \"ks1\" for the code to work.\n\n_You can technically use whatever you want and update the code to reflect the keyspace name. This is really to get you on a happy path for the first run._\n\n- **For provider and region**: Choose GCP as a provider. Region is where your database will reside physically (choose one close to you or your users...you may not have a lot of \"free\" choices).\n\n- **Create the database**. Review all the fields to make sure they are as shown, and click the `Create Database` button.\n\n- **Save your secure token details**: It's a good idea to save the auto-generated token details off at this point.  You can click the \"Copy\" icon or download them locally as a JSON file.\n\nYou will see your new database `pending` in the Dashboard.\n\n![my-pic](https://github.com/datastaxdevs/shared-assets/blob/master/astra/dashboard-pending-1000-update.png?raw=true)\n\nThe 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.\n\n## 2. Working with Cassandra\n\n**✅ Check that our keyspace exist**\n\nClick your database name, locate the `CQL Console` TAB and enter this first command:\n\n```sql\ndescribe keyspaces;\n```\n\n**✅ Create Entities**\n\n```sql\nuse ks1;\n\nCREATE TYPE IF NOT EXISTS video_format (\n  width   int,\n  height  int\n);\n\nCREATE TABLE IF NOT EXISTS videos (\n videoid   uuid,\n title     text,\n upload    timestamp,\n email     text,\n url       text,\n tags      set \u003ctext\u003e,\n frames    list\u003cint\u003e,\n formats   map \u003ctext,frozen\u003cvideo_format\u003e\u003e,\n PRIMARY KEY (videoid)\n);\n\ndescribe ks1;\n```\n\n**✅ Use the data model** :\n\n- Insert value using plain CQL\n\n```sql\nINSERT INTO videos(videoid, email, title, upload, url, tags, frames, formats)\nVALUES(uuid(), 'clu@sample.com', 'sample video',\n     toTimeStamp(now()), 'http://google.fr',\n     { 'cassandra','accelerate','2020'},\n     [ 1, 2, 3, 4],\n     { 'mp4':{width:1,height:1},'ogg':{width:1,height:1}});\n\nINSERT INTO videos(videoid, email, title, upload, url)\nVALUES(uuid(), 'clu@sample.com', 'video2', toTimeStamp(now()), 'http://google.fr');\n```\n\n- Insert Value using JSON\n\n```sql\nINSERT INTO videos JSON '{\n   \"videoid\":\"e466f561-4ea4-4eb7-8dcc-126e0fbfd573\",\n     \"email\":\"clunven@sample.com\",\n     \"title\":\"A Second videos\",\n     \"upload\":\"2020-02-26 15:09:22 +00:00\",\n     \"url\": \"http://google.fr\",\n     \"frames\": [1,2,3,4],\n     \"tags\":   [ \"cassandra\",\"accelerate\", \"2020\"],\n     \"formats\": {\n        \"mp4\": {\"width\":1,\"height\":1},\n        \"ogg\": {\"width\":1,\"height\":1}\n     }\n}';\n```\n\n- Read values\n\n```sql\nselect * from videos;\n```\n\n- Read by id\n```sql\nselect * from videos where videoid=e466f561-4ea4-4eb7-8dcc-126e0fbfd573;\n```\n\n[🏠 Back to Table of Contents](#table-of-content)\n\n## 3. Working with REST API\n\nTo use the API we will need a token please create a token following the instructions here:\n\n#### ✅ 3a. Create a token\n\nFollow the documentation to [create a token for your app](https://docs.datastax.com/en/astra/docs/manage-application-tokens.html).\n\nRole: `Database Administrator`\n\nCopy the token value (eg `AstraCS:KDfdKeNREyWQvDpDrBqwBsUB:ec80667c....`) in your clipboard and save the CSV this value would not be provided afterward.\n\n_If you have your auto-generated token details from before, you should be able to skip this step._\n\n**👁️ Expected output**\n\n![image](pics/astra-token.png?raw=true)\n\nNow launch the swagger UI\n\n - Click on the \"Connect\" tab at the top, and then on the \"REST API\" entry in the left nav.\n\n![image](pics/stargate-connect-restapi.png?raw=true)\n\nScroll down to the \"Launching Swagger UI\" section, and click the link.\n\n_Everyone's Swagger UI link will be unique to their instance of Astra DB._\n\n![image](pics/launch-swagger.png?raw=true)\n\nYou can also follow the link to the [REST API Quick Start](https://stargate.io/docs/stargate/1.0/quickstart/quick_start-rest.html) and run Stargate locally. Here we will use the [SwaggerUI](http://localhost:8082/swagger-ui/#/data).\n\n#### ✅ 3b. List keyspaces\n\n- Scroll to the \"schemas\" section of the Swagger spec.\n\n- For all exercises, remember that we're using the *v2* API version.\n\n- [`GET: /v2/schemas/keyspaces`](http://localhost:8082/swagger-ui/#/schemas/getAllKeyspaces)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-list-keyspace.png?raw=true)\n\n- Click `Try it out`\n- Provide your token in the field `X-Cassandra-Token`\n- Click on `Execute`\n\n#### ✅ 3c. List Tables\n\n- [GET /v2/schemas/keyspaces/{keyspaceName}/tables](http://localhost:8082/swagger-ui/#/schemas/getAllTables)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-list-tables.png?raw=true)\n\n- Click `Try it out`\n- Provide your token in the field `X-Cassandra-Token`\n- keyspace: `ks1`\n- Click on `Execute`\n\n#### ✅ 3d. List Types\n\n- [GET /v2/schemas/keyspaces/{keyspaceName}/types](http://localhost:8082/swagger-ui/#/schemas/findAll)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-list-types.png?raw=true)\n\n- Click `Try it out`\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- keyspace: `ks1`\n- Click on `Execute`\n\n#### ✅ 3e Create a Table\n\n- [POST /v2/schemas/keyspaces/{keyspaceName}/tables](http://localhost:8082/swagger-ui/#/schemas/createTable)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-create-table.png?raw=true)\n\n- Click `Try it out`\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- keyspace: `ks1`\n- Data\n```json\n{\n  \"name\": \"users\",\n  \"columnDefinitions\":\n    [\n        {\n        \"name\": \"firstname\",\n        \"typeDefinition\": \"text\"\n      },\n        {\n        \"name\": \"lastname\",\n        \"typeDefinition\": \"text\"\n      },\n      {\n        \"name\": \"email\",\n        \"typeDefinition\": \"text\"\n      },\n        {\n        \"name\": \"color\",\n        \"typeDefinition\": \"text\"\n      }\n    ],\n  \"primaryKey\":\n    {\n      \"partitionKey\": [\"firstname\"],\n      \"clusteringKey\": [\"lastname\"]\n    },\n  \"tableOptions\":\n    {\n      \"defaultTimeToLive\": 0,\n      \"clusteringExpression\":\n        [{ \"column\": \"lastname\", \"order\": \"ASC\" }]\n    }\n}\n```\n\n**👁️ Expected output**\n\n```json\n{\n  \"name\": \"users\"\n}\n```\n\n#### ✅ 3f. Insert Rows\n\n*Notice for the DML you scroll to the `data` section. Make sure you are using url with `V2`, `V1` would also work but this is NOT the same payload.*\n\n- [POST /v2/keyspaces/{keyspaceName}/{tableName}](http://localhost:8082/swagger-ui/#/data/createRow)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-addrows.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- keyspaceName: `ks1`\n- tableName: `users`\n- Data\n```json\n{   \n    \"firstname\": \"Cedrick\",\n    \"lastname\": \"Lunven\",\n    \"email\": \"c.lunven@gmail.com\",\n    \"color\": \"blue\"\n}\n```\n\nYou can note that the output code is `201` and return your primary key `{ \"firstname\": \"Cedrick\",\"lastname\": \"Lunven\" }\n\n- You can add a second record changing only the payload\n```json\n{\n    \"firstname\": \"David\",\n    \"lastname\": \"Gilardi\",\n    \"email\": \"d.gilardi@gmail.com\",\n    \"color\": \"blue\"\n}\n```\n\n- Add a third\n```json\n{\n    \"firstname\": \"Kirsten\",\n    \"lastname\": \"Hunter\",\n    \"email\": \"k.hunter@gmail.com\",\n    \"color\": \"pink\"\n}\n```\n\n#### ✅ 3g. Read multiple rows\n\n- [GET /v2/keyspaces/{keyspaceName}/{tableName}/rows](http://localhost:8082/swagger-ui/#/data/getAllRows_1)\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-listrows.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- keyspaceName: `ks1`\n- tableName: `users`\n- Click Execute\n\n- Notice how now you can only limited return fields\n\n- fields: `firstname, lastname`\n\n#### ✅ 3h. Read a single partition\n\n- [GET /v2/keyspaces/{keyspaceName}/{tableName}/{primaryKey}](http://localhost:8082/swagger-ui/#/data/getRows_1)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-readrows.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- keyspaceName: `ks1`\n- tableName: `users`\n- primaryKey; 'Cedrick`\n- Click Execute\n\n```diff\n- 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.\n```\n\n#### ✅ 3i. Delete a row\n\n- [DELETE /v2/keyspaces/{keyspaceName}/{tableName}/{primaryKey}](http://localhost:8082/swagger-ui/#/data/deleteRows)\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-deleterows.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- keyspaceName: `ks1`\n- tableName: `users`\n- primaryKey; 'Cedrick`\n- Click Execute\n\n## 4. Working with DOCUMENT API\n\nThis walkthrough has been realized using the [Quick Start](https://stargate.io/docs/stargate/1.0/quickstart/quick_start-document.html)\n\nScroll to the top to locate the \"documents\" section in the Swagger UI.\n\n![image](pics/swagger-docs.png?raw=true)\n\n**✅ 4a. List Namespaces** :\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-doc-listnamespaces.png?raw=true)\n\n- Fill with Header `X-Cassandra-Token` with `\u003cyour_token\u003e`\n\n**👁️ Expected output**\n```json\n{\n  \"data\": [\n    { \"name\": \"system_distributed\" },\n    { \"name\": \"system\" },\n    { \"name\": \"data_endpoint_auth\"},\n    { \"name\": \"system_schema\"},\n    { \"name\": \"ks1\" },\n    { \"name\": \"stargate_system\"},\n    { \"name\": \"system_auth\" },\n    { \"name\": \"system_traces\"}\n  ]\n}\n```\n\n**✅ 4b. Create a document** :\n\n*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.*\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-doc-create.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- namespaceName: `ks1`\n- collectionname: `col1`\n- Click `Execute`\n\n```json\n{\n   \"videoid\":\"e466f561-4ea4-4eb7-8dcc-126e0fbfd573\",\n     \"email\":\"clunven@sample.com\",\n     \"title\":\"A Second videos\",\n     \"upload\":\"2020-02-26 15:09:22 +00:00\",\n     \"url\": \"http://google.fr\",\n     \"frames\": [1,2,3,4],\n     \"tags\":   [ \"cassandra\",\"accelerate\", \"2020\"],\n     \"formats\": {\n        \"mp4\": {\"width\":1,\"height\":1},\n        \"ogg\": {\"width\":1,\"height\":1}\n     }\n}\n```\n\n**👁️ Expected output**:\n```json\n{\n  \"documentId\":\"\u003cyour_document_id\u003e\"\n}\n```\n\n**✅ 4c. Retrieve documents** :\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-doc-search.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- namespaceName: `ks1`\n- collectionname: `col1`\n- Click `Execute`\n\n\n**✅ 4d. Retrieve 1 document** :\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-doc-get.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- namespaceName: `ks1`\n- collectionname: `col1`\n- documentId: `\u003cyour_document_id\u003e`\n- Click `Execute`\n\n\n**✅ 4e. Search for document by properties** :\n\n![image](https://raw.githubusercontent.com/datastaxdevs/conference-2021-apachecon-stargate/main/pics/swagger-doc-search.png?raw=true)\n\n- X-Cassandra-Token: `\u003cyour_token\u003e`\n- namespaceName: `ks1`\n- collectionname: `col1`\n- documentId: `\u003cyour_document_id\u003e`\n- WhereClause\n\n```json\n{\"email\": {\"$eq\": \"clunven@sample.com\"}}\n```\n\n[🏠 Back to Table of Contents](#table-of-content)\n\n## 5. Working with GRAPHQL API\n\nThis walkthrough has been realized using the [GraphQL Quick Start](https://stargate.io/docs/stargate/1.0/quickstart/quick_start-graphql.html)\n\n**✅ Creating a keyspace** :\n\nBefore 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.\n\n![image](pics/create-keyspace-1.png?raw=true)\n\nThen provide the keyspace name `library`:\n\n![image](pics/create-keyspace-2.png?raw=true)\n\n**✅ Open GraphQL Playground** :\n\nOpen the playground\n![image](pics/launch-graphql.png?raw=true)\n\n_Everyone's GraphQL Playground link will be unique to their instance of Astra DB._\n\n**👁️ Expected output**\n![image](pics/playground-home.png?raw=true)\n\n**✅ Creating a Table** :\n\n- Use this query\n```\nmutation {\n  books: createTable(\n    keyspaceName:\"library\",\n    tableName:\"books\",\n    partitionKeys: [ # The keys required to access your data\n      { name: \"title\", type: {basic: TEXT} }\n    ]\n    values: [ # The values associated with the keys\n      { name: \"author\", type: {basic: TEXT} }\n    ]\n  )\n  authors: createTable(\n    keyspaceName:\"library\",\n    tableName:\"authors\",\n    partitionKeys: [\n      { name: \"name\", type: {basic: TEXT} }\n    ]\n    clusteringKeys: [ # Secondary key used to access values within the partition\n      { name: \"title\", type: {basic: TEXT}, order: \"ASC\" }\n    ]\n  )\n}\n```\n\n**👁️ Expected output**\n\n![image](pics/graphql-createtables.png?raw=true)\n\n**✅ Populating Table** :\n\nAny of the created APIs can be used to interact with the GraphQL data, to write or read data.\n\nFirst, let’s navigate to your new keyspace `library` inside the playground. Change tab to `graphql` and pick url `/graphql/library`.\n\n- Use this query\n```\nmutation insert2Books {\n  moby: insertbooks(value: {title:\"Moby Dick\", author:\"Herman Melville\"}) {\n    value {\n      title\n    }\n  }\n  catch22: insertbooks(value: {title:\"Catch-22\", author:\"Joseph Heller\"}) {\n    value {\n      title\n    }\n  }\n}\n```\n\n- Don't forget to update the header again\n```\n{\n  \"x-cassandra-token\":\"7c37bda5-7360-4d39-96bc-9765db5773bc\"\n}\n```\n**👁️ Expected output**\n\n![image](pics/graphql-insertdata.png?raw=true)\n\n\n**✅ Read data** :\n\nStay on the same screen and sinmply update the query with\n```\nquery oneBook {\n    books (value: {title:\"Moby Dick\"}) {\n      values {\n        title\n        author\n      }\n    }\n}\n```\n\n**👁️ Expected output**\n\n![image](pics/graphql-readdata.png?raw=true)\n\n[🏠 Back to Table of Contents](#table-of-content)\n\n\n## THE END\n\nCongratulations, you made it to the END!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastaxdevs%2Fconf-grpc-rest-graphql-data-apis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastaxdevs%2Fconf-grpc-rest-graphql-data-apis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastaxdevs%2Fconf-grpc-rest-graphql-data-apis/lists"}