{"id":19903400,"url":"https://github.com/stargate/data-api","last_synced_at":"2026-01-27T00:26:28.826Z","repository":{"id":66104578,"uuid":"564388942","full_name":"stargate/data-api","owner":"stargate","description":"JSON document API for Apache Cassandra (formerly known as JSON API)","archived":false,"fork":false,"pushed_at":"2025-04-28T23:31:11.000Z","size":79095,"stargazers_count":17,"open_issues_count":173,"forks_count":17,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-28T23:38:48.659Z","etag":null,"topics":["api","cassandra","java","javascript","json"],"latest_commit_sha":null,"homepage":"https://stargate.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stargate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-10T16:00:19.000Z","updated_at":"2025-04-26T01:20:27.000Z","dependencies_parsed_at":"2023-09-30T00:04:18.460Z","dependency_job_id":"48c44232-1df7-4edd-9d81-d1c25491202e","html_url":"https://github.com/stargate/data-api","commit_stats":null,"previous_names":["stargate/data-api"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stargate%2Fdata-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stargate%2Fdata-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stargate%2Fdata-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stargate%2Fdata-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stargate","download_url":"https://codeload.github.com/stargate/data-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252126421,"owners_count":21698963,"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":["api","cassandra","java","javascript","json"],"created_at":"2024-11-12T20:23:35.408Z","updated_at":"2026-01-27T00:26:28.811Z","avatar_url":"https://github.com/stargate.png","language":"Java","readme":"# Stargate Data API\n\nThis project implements the stand-alone Data API microservice for Stargate.\nData API is an HTTP service that gives access to data stored in a Cassandra cluster using a JSON Document based interface.\n\nSpecifications and design documents for this service are defined in the [docs](docs) directory.\n\n\n##### Table of Contents\n* [Quick Start](#quick-start)\n* [Concepts](#concepts)\n    * [Shared concepts](#shared-concepts)\n* [Configuration properties](#configuration-properties)\n* [Development guide](#development-guide)\n    * [Running the application in dev mode](#running-the-application-in-dev-mode)\n    * [Running integration tests](#running-integration-tests)\n    * [Packaging and running the application](#packaging-and-running-the-application)\n    * [Creating a native executable](#creating-a-native-executable)\n    * [Creating a docker image](#creating-a-docker-image)\n* [Quarkus Extensions](#quarkus-extensions)\n\n## Quick Start\n\nMost users will want to use the Data API through a client library such as the [stargate-mongoose](https://github.com/stargate/stargate-mongoose) for JavaScript development. See the [stargate-mongoose-sample-apps](https://github.com/stargate/stargate-mongoose-sample-apps) for a quick demonstration.\n\nThe quickest way to test out the Data API directly is to start a local copy of the service and supporting infrastructure using the [Docker compose](docker-compose) scripts:\n\n```shell\ncd docker-compose\n./start_hcd.sh\n# or\n./start_dse69.sh\n```\n\nThis starts an instance of the Data API along with a backend database (HCD or DSE 6.9)\n\n\u003e **Warning**\n\u003e Running this script with no options will use the latest `v1` tagged version of Data API. Therefore, if you have these tags already present in your local Docker from other development/testing, those are the images that will be used. See our Docker compose [README](docker-compose/README.md) to see additional options.\n\nOnce the services are up, you can access the Swagger endpoint at: http://localhost:8181/swagger-ui/\n\nWe also have a Postman collection you can use to learn about the various operations supported by the Data API as part of the [Stargate-Cassandra](https://www.postman.com/datastax/workspace/stargate-cassandra/overview) workspace. \n\n## Concepts\n\n## Configuration properties\n\nThere are two main configuration property prefixes used, `stargate.` and `quarkus.`.\n\nThe `quarkus.` properties are defined by the Quarkus framework, and the complete list of available properties can be found on the [All configuration options](https://quarkus.io/guides/all-config) page.\nIn addition, the related guide of each [Quarkus extension](#quarkus-extensions) used in the project provides an overview of the available config options.\n\nThe `stargate.` properties are defined by this project itself.\nThe properties are defined by dedicated config classes annotated with the `@ConfigMapping`.\nThe list of currently available properties is documented in the [Configuration Guide](CONFIGURATION.md).\n\n## Development guide\n\nThis project uses Quarkus, the Supersonic Subatomic Java Framework.\nIf you want to learn more about Quarkus, please visit its [website](https://quarkus.io/).\n\nIt's recommended that you install Quarkus CLI in order to have a better development experience.\nSee [CLI Tooling](https://quarkus.io/guides/cli-tooling) for more information.\n\nNote that this project uses Java 21, please ensure that you have the target JDK installed on your system.\n\n### Running the application in dev mode\n\nYou can run your application in dev mode that enables live coding using:\n```shell script\ndocker run -d --rm -e CLUSTER_NAME=dse-cluster -e CLUSTER_VERSION=6.8 -e ENABLE_AUTH=true -e DEVELOPER_MODE=true -e DS_LICENSE=accept -e DSE=true -p 8081:8081 -p 8091:8091 -p 9042:9042 stargateio/coordinator-dse-next:v2\n\n./mvnw compile quarkus:dev -Dstargate.jsonapi.operations.vectorize-enabled=true \\\n  -Dstargate.jsonapi.operations.database-config.local-datacenter=dc1\n```\n\nThe command above will first spin the single Stargate DSE coordinator in dev that the API would communicate to.\n\n\u003e **_NOTE:_**  Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8181/stargate/dev/.\n\n#### Debugging\n\nIn development mode, Quarkus starts by default with debug mode enabled, listening to port `5005` without suspending the JVM.\nYou can attach the debugger at any point, the simplest option would be from IntelliJ using `Run -\u003e Attach to Process`.\n\nIf you wish to debug from the start of the application, start with `-Ddebug=client` and create a debug configuration in a *Listen to remote JVM* mode.\n\nSee [Debugging](https://quarkus.io/guides/maven-tooling#debugging) for more information.\n\n### Running integration tests\n\nIntegration tests are using the [Testcontainers](https://www.testcontainers.org/) library in order to set up all needed dependencies, a Stargate coordinator and a Cassandra data store.\nThey are separated from the unit tests and are running as part of the `integration-test` and `verify` Maven phases:\n\n```shell script\n./mvnw integration-test\n```\n\n#### Running from IDE\n\nRunning integration tests from an IDE is supported out of the box.\nThe tests will use the DSE Next as the data store by default.\nRunning a test with a different version of the data store or the Stargate coordinator requires changing the run configuration and specifying the following system properties:\n\n* `testing.containers.cassandra-image` - version of the Cassandra docker image to use, for example: `stargateio/dse-next:4.0.7-336cdd7405ee`\n* `testing.containers.stargate-image` - version of the Stargate coordinator docker image to use, for example: `stargateio/coordinator-4_0:v2.1` (must be V2.1 coordinator for the target data store)\n* `testing.containers.cluster-dse` - optional and only needed if coordinator is used\n\n#### Executing against a running application\n\nThe integration tests can also be executed against an already running instance of the application.\nThis can be achieved by setting the `quarkus.http.test-host` system property when running the tests.\nYou'll most likely need to specify the authentication token to use in the tests, by setting the `stargate.int-test.auth-token` system property.\n\n```shell\n./mvnw verify -DskipUnitTests -Dquarkus.http.test-host=1.2.3.4 -Dquarkus.http.test-port=4321 -Dstargate.int-test.auth-token=[AUTH_TOKEN]\n\n```\n\n#### Skipping integration tests\n\nYou can skip the integration tests during the maven build by disabling the `int-tests` profile using the `-DskipITs` property:\n\n```shell script\n./mvnw verify -DskipITs\n```\n\n#### Skipping unit tests\n\nAlternatively you may want to run only integration tests but not unit tests (especially when changing integration tests).\nThis can be achieved using the command:\n\n```\n./mvnw verify -DskipUnitTests\n```\n\n#### Troubleshooting failure to run ITs\n\nIf your Integration Test run fails with some generic, non-descriptive error like:\n\n```\n[ERROR]   CollectionsResourceIntegrationTest » Runtime java.lang.reflect.InvocationTargetException\n```\n\nhere are some things you should try:\n\n* Make sure your Docker Engine has enough resources. For example following have been observed:\n    * Docker Desktop defaults of 2 gigabytes of memory on Mac are not enough: try at least 4\n\n### Packaging and running the application\n\nThe application can be packaged using:\n```shell script\n./mvnw package\n```\nIt produces the `quarkus-run.jar` file in the `target/quarkus-app/` directory.\nBe aware that it’s not an _über-jar_ as the dependencies are copied into the `target/quarkus-app/lib/` directory.\n\nThe application is now runnable using `java -jar target/quarkus-app/quarkus-run.jar`.\n\nIf you want to build an _über-jar_, execute the following command:\n```shell script\n./mvnw package -Dquarkus.package.type=uber-jar\n```\n\nThe application, packaged as an _über-jar_, is now runnable using `java -jar target/*-runner.jar`.\n\n### Creating a Docker image\n\nYou can create a Docker image named `io.stargate/jsonapi` using:\n```shell script\n./mvnw clean package -Dquarkus.container-image.build=true\n```\n\n\u003e NOTE: Include the property `-Dquarkus.docker.buildx.platform=linux/amd64,linux/arm64` if you want to build for multiple platforms.\n\nOr, if you want to create a native-runnable Docker image named `io.stargate/jsonapi-native` using:\n```shell script\n./mvnw clean package -Pnative -Dquarkus.native.container-build=true -Dquarkus.container-image.build=true\n```\n\nYou can create a JVM-based Docker image (`stargateio/jsonapi-profiling`) with additional profiling tools by using:\n```shell script\n./mvnw -B -ntp package -DskipTests -Dquarkus.container-image.build=true -Dquarkus.container-image.name=jsonapi-profiling -Dquarkus.docker.dockerfile-jvm-path=src/main/docker/Dockerfile-profiling.jvm\n```\n\nIf you want to learn more about building container images, please consult [Container images](https://quarkus.io/guides/container-image).\n\n## Quarkus Extensions\n\nThis project uses various Quarkus extensions, modules that run on top of a Quarkus application.\nYou can list, add and remove the extensions using the `quarkus ext` command.\n\n### `quarkus-arc`\n[Related guide](https://quarkus.io/guides/cdi-reference)\n\nThe Quarkus DI solution.\n\n### `quarkus-container-image-docker`\n[Related guide](https://quarkus.io/guides/container-image)\n\nThe project uses Docker for building the Container images.\nProperties for Docker image building are defined in the [pom.xml](pom.xml) file.\nNote that under the hood, the generated Dockerfiles under [src/main/docker](src/main/docker) are used when building the images.\nWhen updating the Quarkus version, the Dockerfiles must be re-generated.\n\n### `quarkus-smallrye-health`\n[Related guide](https://quarkus.io/guides/smallrye-health)\n\nThe extension setups the health endpoints under `/stargate/health`.\n\n### `quarkus-smallrye-openapi`\n[Related guide](https://quarkus.io/guides/openapi-swaggerui)\n\nThe OpenAPI definitions are generated and available under `/api/json/openapi` endpoint.\nThe [StargateJsonApi](src/main/java/io/stargate/sgv2/jsonapi/StargateJsonApi.java) class defines the `@OpenAPIDefinition` annotation.\nThis definition defines the default *SecurityScheme* named `Token`, which expects the header based authentication with the HTTP Header `Token`.\nThe `info` portions of the Open API definitions are set using the `quarkus.smallrye-openapi.info-` configuration properties.\n\n## Cassandra Backend\n\nThe Data API supports running against a Cassandra backend supporting the latest Storage Attached Index (SAI) features, currently available in DataStax Enterprise (DSE) 6.9 and DataStax Hyper-Converged Database (HCD). \n\n### Updating the DSE/HCD version\n\nWe regularly update the integration tests and [Docker compose](docker-compose) scripts to support the latest versions of DSE and HCD. To update the version of DSE or HCD that the Data API runs against, the following prodcedure is recommended:\n\n- Update the `pom.xml` file to reference the correct Docker image. For example, for the `dse69-it` profile, update the `testing.containers.cassandra-image` property to the desired version:\n\n  ```\n  \u003cstargate.int-test.cassandra.image-tag\u003e6.9.0\u003c/stargate.int-test.cassandra.image-tag\u003e\n  ```\n\n- Update the `docker-compose` scripts to reference the correct Docker image. \n  - This includes the `docker-compose/.env` file. For example, you would update the `DSETAG` or `HCDTAG` as follows: \n\n    ```\n    DSETAG=6.9.0\n    ```\n    \n  - Also update the appropriate `docker-compose/start-dse69.sh` or `docker-compose/start-hcd.sh` script to reference the new version as the default, similar to the update in the `docker-compose/.env` file.\n\n- Merge any changes from the reference configuration file in the DSE/HCD repo to the copies in this repo.\n  - The local copies override the default configuration to set the desired authentication configuration used on the DSE/HCD backend when running in Docker compose or integration tests. \n  - Sometimes, a new release of DSE/HCD will include new configuration options that we will want to make sure are set in our local configuration, so we don't get out of sync.\n  - We will want to merge any changes in the source configuration file while preserving our own updates to the authentication configuration.\n  - For DSE 6.9, you will want to review/update, the files `src/test/resources/dse.yaml` and `docker-compose/dse.yaml` based on the [latest version](https://github.com/riptano/bdp/blob/6.9-dev/resources/dse/conf/dse.yaml). The two local copies should have the same contents.\n  - For HCD, you will want to review/update, the files `src/test/resources/dse.yaml` and `docker-compose/dse.yaml` based on the [latest version](https://github.com/riptano/bdp/blob/7.0-dev/conf/cassandra.yaml). The two local copies should have the same contents.\n\n### Run Data API against on-prem DSE/HCD\n- Have your Backend DSE/HCD ready, package Data API as `quarkus-run.jar` to the `target/quarkus-app/` directory. \n    ```\n    ./mvnw clean package -DskipTests\n    ```\n- The application is now runnable using `java -jar target/quarkus-app/quarkus-run.jar`. Set the correct `local-datacenter` as the jvm option. \n    ```\n     java -Dstargate.jsonapi.operations.database-config.local-datacenter=dc1 -jar target/quarkus-app/quarkus-run.jar\n    ```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstargate%2Fdata-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstargate%2Fdata-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstargate%2Fdata-api/lists"}