datastax/cassandra-data-apis

Easy to use APIs for accessing data stored in Apache Cassandra.These APIs can be used as a standalone server using either Docker or manuallyrunning a server. They can also be embedded in existing applications using HTTProutes.Currently, this project provides GraphQL APIs. Other API types are possible inthe future.Getting StartedInstallationdocker pull datastaxlabs/cassandra-data-apisdocker run -p 8080:8080 -e DATA_API_HOSTS=<cassandra_hosts_here> datastaxlabs/cassandra-data-apisYou can also manually build the docker image and/or the server using theinstructions below.Running in the backgroundYou can start the container in detached mode by using -d and --rm flags.docker run --rm -d -p 8080:8080 -e DATA_API_HOSTS=<cassandra_hosts_here> datastaxlabs/cassandra-data-apisRunning on macOS or Windows for development purposesWhen using Docker for Desktop, if your Cassandra instance is listening on the loopback address 127.0.0.1,you can use host.docker.internal name which resolves to the internal IP address used by the host.docker run -p 8080:8080 -e DATA_API_HOSTS=host.docker.internal datastaxlabs/cassandra-data-apisUsing GraphQLBy default, a GraphQL endpoint is started and will generate a GraphQL schema per keyspace. You need at least oneuser-defined keyspace in your database to get started.Use the GraphQL documentation for getting started.ConfigurationConfiguration for Docker can be done using either environment variables, amounted configuration file, or both.Add additional configuration using environment variables by adding them to thedocker run command.docker run -e DATA_API_HOSTS=127.0.0.1 -e DATA_API_KEYSPACE=example ...Using a configuration fileTo use a configuration file, create a file with the following contents:hosts: # Change to your cluster's hosts - 127.0.0.1# keyspace: example# username: cassandra# password: cassandra# See the "Settings" section for additional configurationThen start docker with:docker run -p 8080:8080 -v "${PWD}/<your_config_file>.yaml:/root/config.yaml" datastaxlabs/cassandra-data-apisSettingsNameTypeEnv. VariableDescriptionhostsstringsDATA_API_HOSTSHosts for connecting to the databasekeyspacestringDATA_API_KEYSPACEOnly allow access to a single keyspaceexcluded-keyspacesstringsDATA_API_EXCLUDED_KEYSPACESKeyspaces to exclude from the endpointusernamestringDATA_API_USERNAMEConnect with database userpasswordstringDATA_API_PASSWORDDatabase user's passwordoperationsstringsDATA_API_OPERATIONSA list of supported schema management operations. See below. (default "TableCreate, KeyspaceCreate")request-loggingboolDATA_API_REQUEST_LOGGINGEnable request loggingschema-update-intervaldurationDATA_API_SCHEMA_UPDATE_INTERVALInterval in seconds used to update the graphql schema (default 10s)ssl-enabledboolDATA_API_SSL_ENABLEDEnable SSL (client-to-node encryption)?ssl-ca-cert-pathstringDATA_API_SSL_CA_CERT_PATHSSL CA certificate pathssl-client-cert-pathstringDATA_API_SSL_CLIENT_CERT_PATHSSL client certificate pathssl-client-key-pathstringDATA_API_SSL_CLIENT_KEY_PATHSSL client private key pathssl-host-verificationstringDATA_API_SSL_HOST_VERIFICATIONVerify the peer certificate? It is highly insecure to disable host verification (default true)start-graphqlboolDATA_API_START_GRAPHQLStart the GraphQL endpoint (default true)graphql-pathstringDATA_API_GRAPHQL_PATHGraphQL endpoint path (default "/graphql")graphql-portintDATA_API_GRAPHQL_PORTGraphQL endpoint port (default 8080)graphql-schema-pathstringDATA_API_GRAPHQL_SCHEMA_PATHGraphQL schema management path (default "/graphql-schema")Configuration TypesThe strings type expects a comma-delimited list e.g. 127.0.0.1, 127.0.0.2, 127.0.0.3 when using environment variables or a command flag, and it expectsan array type when using a configuration file.YAML:--- host: - "127.0.0.1" - "127.0.0.2" - "127.0.0.3"JSON:{ "hosts": ["127.0.0.1", "127.0.0.2", "127.0.0.3"]}Schema Management OperationsOperationAllowsTableCreateCreation of tablesTableDropRemoval of tablesTableAlterAddAdd new table columnsTableAlterDropRemove table columnsKeyspaceCreateCreation of keyspacesKeyspaceDropRemoval of keyspacesTLS/SSLHTTPSThe API endpoint does not currently support HTTPS natively, but it can be handled by a gateway orreverse proxy. More information about protecting the API endpoint can be found in thisdocumentation.Client-to-node EncryptionBy default, traffic between the API endpoints and the database servers is not encrypted. To securethis traffic you will need to generate SSL certificates and enable SSL on the database servers. Moreinformation about enabling SSL (client-to-node encryption) on the database servers can be found inthis documentation. After SSL is enabled on the database servers use thessl-enabled option, along with ssl-ca-cert-path to enable secure connections. ssl-ca-cert-pathis a path to the chain of certificates used to generate the database server's certificates. Thecertificate chain is used by API endpoints to verify the database server's certificates. Thessl-client-cert-path and ssl-client-key-path options are not required, but can be use to provideclient-side certificates that are used by the database servers to authenticate and verify the APIservers, this is known as mutual authentication.BuildingThis section is mostly for developers. Pre-built docker image recommended.Building the Docker Imagecd <path_to_data-apis>/cassandra-data-apisdocker build -t cassandra-data-apis .Run locally with single node, local Cassandra clustercd <path_to_data-apis>/cassandra-data-apisdocker build -t cassandra-data-apis .# On Linux (with a cluster started on the docker bridge: 172.17.0.1)docker run -p 8080:8080 -e "DATA_API_HOSTS=172.17.0.1" cassandra-data-apis# With a cluster bound to 0.0.0.0docker run --network host -e "DATA_API_HOSTS=127.0.0.1" cassandra-data-apis# On macOS (with a cluster bound to 0.0.0.0)docker run -p 8080:8080 -e "DATA_API_HOSTS=host.docker.internal" cassandra-data-apisThese host values can also be used in the configuration file approach used inthe previous section.Build and run as a standalone webserverIf you want to run this module as a standalone webserver, use:# Define the keyspace you want to use# Start the webservergo build run.exe && ./run.exe --hosts 127.0.0.1 --keyspace storeYour settings can be persisted using a configuration file:hosts: - 127.0.0.1keyspace: storeoperations: - TableCreate - KeyspaceCreateport: 8080schema-update-interval: 30sTo start the server using a configuration file, use:./run.exe --config <your_config_file>.yamlSettings can also be overridden using environment variables prefixed withDATA_API_:DATA_API_HOSTS=127.0.0.1 DATA_API_KEYSPACE=store ./run.exe --config <your_config_file>.yamlPlugin the routes within your HTTP request routerInstallationgo get github.com/datastax/cassandra-data-apisUsing the APITo add the routes to your existing HTTP request router, use:cfg := endpoint.NewEndpointConfig("your.first.contact.point", "your.second.contact.point")// Setup config here using your env variablesendpoint, err := cfg.NewEndpoint()if err != nil { log.Fatalf("unable create new endpoint: %s", err)}keyspace := "store"routes, err = endpoint.RoutesKeyspaceGraphQL("/graphql", keyspace)// Setup routes on your http routerLicense© DataStax, Inc.Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance withthe License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed onan "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for thespecific language governing permissions and limitations under the License.