Skip to main content

Basic REST API Example

This example shows how to run Dochia against a typical REST API using an OpenAPI spec, following the same style and options used across the docs.

Overview​

  • Run your first tests quickly
  • Limit scope by paths, tags, and HTTP methods
  • Control output, performance, and noise

Prerequisites​

  • OpenAPI spec file, e.g. api.yml (-c, --contract)
  • Running API server, e.g. http://localhost:8080 (-s, --server)

Quick Start​

# Minimal run
dochia test -c api.yml -s http://localhost:8080

# Preview without execution
dochia test -c api.yml -s http://localhost:8080 --dry-run

Common Recipes​

Focus Scope​

# Only specific paths
dochia test -c api.yml -s http://localhost:8080 \
  --path "/users" --path "/orders"

# Only specific HTTP methods
dochia test -c api.yml -s http://localhost:8080 \
  --http-method "POST" --http-method "PUT"

# Only specific tags
dochia test -c api.yml -s http://localhost:8080 \
  --tag "user-management" --tag "order-processing"

Playbook Selection​

# Include specific playbooks
dochia test -c api.yml -s http://localhost:8080 \
  --playbook "EmptyStringsInFields" --playbook "NullValuesInFields"

# Or skip specific playbooks
dochia test -c api.yml -s http://localhost:8080 \
  --skip-playbook "VeryLargeStrings" --skip-playbook "LargeNumberOfRandomHeaders"

Response Handling and Noise Reduction​

# Blackbox mode: treat only 5xx as errors
dochia test -c api.yml -s http://localhost:8080 --blackbox

# Hide successful results
dochia test -c api.yml -s http://localhost:8080 --hide-success

# Filter out specific response codes from being reported as issues
dochia test -c api.yml -s http://localhost:8080 \
  --filter-codes "2xx,4xx"

Output and Reporting​

# Custom output folder and lighter HTML format (no JS)
dochia test -c api.yml -s http://localhost:8080 \
  --output ./reports --output-format HTML_ONLY --timestamp-reports

# Execution statistics
dochia test -c api.yml -s http://localhost:8080 \
  --execution-stats --detailed-execution-stats

Headers and Query Params​

# Inline headers
dochia test -c api.yml -s http://localhost:8080 \
  -H "Authorization=Bearer $TOKEN" \
  -H "X-Request-Id=$(uuidgen)"

# Headers from YAML file (root key: all)
# headers.yml
# all:
#   Authorization: "Bearer $TOKEN"
#   X-Request-Id: "$(uuidgen)"

dochia test -c api.yml -s http://localhost:8080 --headers headers.yml

# Extra query params (inline)
dochia test -c api.yml -s http://localhost:8080 -Q "env=dev"

# Query params from YAML file
# query.yml
# all:
#   env: "dev"

dochia test -c api.yml -s http://localhost:8080 --query-params query.yml

Reference Data (Required Field Values)​

# Inline for all requests
dochia test -c api.yml -s http://localhost:8080 \
  -R "tenantId=company123"

# From YAML file (per-path overrides)
# reference.yml
# /users:
#   tenantId: "company123"

dochia test -c api.yml -s http://localhost:8080 --reference-data reference.yml

Security Tips​

  • Mask sensitive headers in console and reports: 
    --mask-headers "Authorization,X-API-Key"
  • Prefer environment variables for secrets. Avoid committing tokens.
  • Limit scope while validating auth (paths, tags, methods).

Troubleshooting​

  • Validate available paths: 
    dochia list --paths -c api.yml
  • Inspect what will run without executing: 
    dochia test -c api.yml -s http://localhost:8080 --dry-run -j
  • Increase verbosity: -vvv
  • Rate limiting/timeout tuning: 
    dochia test -c api.yml -s http://localhost:8080 \
      --max-requests-per-minute 500 \
      --connection-timeout 30 --read-timeout 30 --write-timeout 30

See Also​