The Data Contract CLI can run as a web server that exposes a REST API for data contract testing, linting, exporting, and changelogs. This is useful for integrating data contract checks into other services.
You can try a public demo at api.datacontract.com. Note that the demo endpoint cannot connect to your secured data sources.
The API requires the api extra:
pip install 'datacontract-cli[api]'
Start the server:
datacontract api
| Option | Default | Description |
|---|---|---|
--port |
4242 |
Bind the socket to this port. |
--host |
127.0.0.1 |
Bind to this host. In Docker, use 0.0.0.0. |
--debug / --no-debug |
--no-debug |
Enable debug logging. |
You can pass extra keyword arguments through to uvicorn.run(), e.g.:
datacontract api --port 1234 --root_path /datacontract
Once running, open the interactive OpenAPI documentation (Swagger UI) at http://localhost:4242. You can execute the commands directly from the UI.
POST a data contract as the request body to /test and receive the test results as JSON:
curl -X POST "http://localhost:4242/test?server=production" \
--data-binary @datacontract.yaml
You can also send the YAML inline with -H 'Content-Type: application/yaml'.
curl -X POST "http://localhost:4242/export?format=sql" \
--data-binary @datacontract.yaml
POST a JSON body with v1 (before) and v2 (after) as YAML strings. The response is a JSON object with summary and entries:
curl -X POST "http://localhost:4242/changelog" \
-H "Content-Type: application/json" \
-d '{
"v1": "'"$(cat v1.odcs.yaml)"'",
"v2": "'"$(cat v2.odcs.yaml)"'"
}'
To connect to a data source, set the required credentials as environment variables before starting the API (see Testing). For example, for Snowflake:
export DATACONTRACT_SNOWFLAKE_USERNAME=123
export DATACONTRACT_SNOWFLAKE_PASSWORD=
export DATACONTRACT_SNOWFLAKE_WAREHOUSE=
export DATACONTRACT_SNOWFLAKE_ROLE=
Set DATACONTRACT_CLI_API_KEY to a secret value (such as a random UUID) to require authentication. Requests must then include the header x-api-key with the correct key.
export DATACONTRACT_CLI_API_KEY=<your-secret-key-such-as-a-random-uuid>
:::warning Securing the API is highly recommended. Data contract tests may otherwise be subject to SQL injection or leak sensitive information. :::
The pre-built image can run the API in any container environment (Docker Compose, Kubernetes, Azure Container Apps, Google Cloud Run, …):
services:
datacontract-api:
image: datacontract/cli:latest
ports:
- "4242:4242"
environment:
- DATACONTRACT_CLI_API_KEY=a079ce4c-af90-45ab-abe5-a8d7697f60d6
command: ["api", "--host", "0.0.0.0"]
See the api command reference.
