Skip to main content

HTTP API

Test APIs that return data in JSON format. Currently, only GET requests are supported.

1. Install​

No extra is required for API connections:

uv tool install --python python3.11 --upgrade datacontract-cli

See Installation for pip, pipx, and Docker.

2. Set credentials​

If the API requires authentication, set the value for the authorization header:

# .env
DATACONTRACT_API_HEADER_AUTHORIZATION="Bearer <token>"

For public endpoints, skip this step.

3. Create a contract from a response​

Fetch one response and import its schema, then point the generated servers block at the endpoint:

curl -o response.json https://api.example.com/orders
datacontract import json --source response.json --output datacontract.yaml

The import generates a servers entry of type: local. Replace it with the API endpoint:

servers:
  - server: api
    type: api
    location: "https://api.example.com/orders"
    delimiter: none # new_line, array, or none (default)

4. Test the actual data​

datacontract test datacontract.yaml
🟢 data contract is valid. Run 12 checks. Took 1.8 seconds.

5. Let it catch a violation​

The contract becomes valuable when it detects drift. Tighten an expectation — for example, mark a field as required: true, restrict a status field to its allowed values, or add a quality rule. Run datacontract test datacontract.yaml again: every violation is listed as an error, and the command exits with code 1 — ready for CI/CD scheduling so you catch drift before your consumers do.

Reference​

Authentication options and data type handling: HTTP API Reference.

Troubleshooting​

  • 401 / 403 — set DATACONTRACT_API_HEADER_AUTHORIZATION including the scheme (e.g. Bearer eyJ...), not just the raw token.
  • Schema checks fail on a wrapped response — if the API returns {"data": [...]} instead of a plain array, model the wrapper object in the schema, or set delimiter accordingly (array for a JSON array of records, none for a single object).