API Testing Quick Reference

API Testing Quick Reference

This guide provides ready-to-use curl commands for testing the HTTP gateway.

Prerequisites

Start the HTTP gateway server:

cargo run --example http_server

The server will listen on http://localhost:8080

Authentication Tokens

JWT Token (Snowflake)

For testing, use this JWT token (expires in year 2286):

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU

Bearer Token (Databricks)

Any token starting with dapi:

dapi1234567890ab

API Key (Pinecone)

Any string with 32+ characters:

12345678901234567890123456789012

Snowflake API Tests

1. Create Session

curl -X POST http://localhost:8080/snowflake/session \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "analytics_db",
    "schema": "public",
    "warehouse": "compute_wh",
    "role": "analyst"
  }' | jq

Expected Response:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "database": "analytics_db",
  "schema": "public",
  "warehouse": "compute_wh",
  "role": "analyst"
}

2. Submit Query

curl -X POST http://localhost:8080/snowflake/queries \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, name, email FROM users WHERE active = true ORDER BY created_at DESC LIMIT 100"
  }' | jq

Expected Response:

{
  "query_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "QUEUED"
}

Save the query_id for the next commands.

3. Check Query Status

QUERY_ID="7c9e6679-7425-40de-944b-e07fc1f90ae7"

curl -X GET http://localhost:8080/snowflake/queries/$QUERY_ID \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" | jq

Expected Response:

{
  "query_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "RUNNING",
  "progress": 50
}

4. Get Query Results (wait ~200ms after submission)

QUERY_ID="7c9e6679-7425-40de-944b-e07fc1f90ae7"

curl -X GET http://localhost:8080/snowflake/queries/$QUERY_ID/result \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" | jq

Expected Response:

{
  "query_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "columns": [
    {"name": "id", "type": "NUMBER"},
    {"name": "name", "type": "VARCHAR"}
  ],
  "rows": [
    [1, "Alice"],
    [2, "Bob"]
  ],
  "row_count": 2
}

5. Cancel Query

QUERY_ID="7c9e6679-7425-40de-944b-e07fc1f90ae7"

curl -X DELETE http://localhost:8080/snowflake/queries/$QUERY_ID \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" | jq

Databricks SQL API Tests

1. Execute SQL Statement

curl -X POST http://localhost:8080/dbsql/sql/statements \
  -H "Authorization: Bearer dapi1234567890ab" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "SELECT * FROM delta.`/mnt/data/users` WHERE country = \"US\" LIMIT 1000",
    "warehouse_id": "abc123xyz"
  }' | jq

Expected Response:

{
  "statement_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": {
    "state": "PENDING"
  }
}

2. Get Statement Status and Results (wait ~200ms)

STMT_ID="01234567-89ab-cdef-0123-456789abcdef"

curl -X GET http://localhost:8080/dbsql/sql/statements/$STMT_ID \
  -H "Authorization: Bearer dapi1234567890ab" | jq

Expected Response (Running):

{
  "statement_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": {
    "state": "RUNNING"
  }
}

Expected Response (Completed):

{
  "statement_id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": {
    "state": "SUCCEEDED"
  },
  "manifest": {
    "schema": {
      "columns": [
        {"name": "id", "type_name": "INT"},
        {"name": "value", "type_name": "STRING"}
      ]
    },
    "total_row_count": 2
  },
  "result": {
    "data_array": [
      [1, "test1"],
      [2, "test2"]
    ]
  }
}

3. Cancel Statement

STMT_ID="01234567-89ab-cdef-0123-456789abcdef"

curl -X POST http://localhost:8080/dbsql/sql/statements/$STMT_ID/cancel \
  -H "Authorization: Bearer dapi1234567890ab" | jq

Pinecone Vector API Tests

1. Create Index

curl -X POST http://localhost:8080/pinecone/indexes \
  -H "x-api-key: 12345678901234567890123456789012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-embeddings",
    "dimension": 384,
    "metric": "cosine"
  }' | jq

Expected Response:

{
  "name": "product-embeddings",
  "dimension": 384,
  "metric": "cosine"
}

2. Upsert Vectors

curl -X POST http://localhost:8080/pinecone/vectors/upsert \
  -H "x-api-key: 12345678901234567890123456789012" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "id": "product-001",
        "values": [0.1, 0.2, 0.3, 0.4, 0.5],
        "metadata": {
          "category": "electronics",
          "price": 299.99,
          "brand": "TechCo"
        }
      },
      {
        "id": "product-002",
        "values": [0.2, 0.3, 0.4, 0.5, 0.6],
        "metadata": {
          "category": "electronics",
          "price": 399.99,
          "brand": "GadgetInc"
        }
      },
      {
        "id": "product-003",
        "values": [0.9, 0.8, 0.7, 0.6, 0.5],
        "metadata": {
          "category": "furniture",
          "price": 899.99,
          "brand": "HomeStyle"
        }
      }
    ]
  }' | jq

Expected Response:

{
  "upserted_count": 3
}

3. Query Similar Vectors

curl -X POST http://localhost:8080/pinecone/query \
  -H "x-api-key: 12345678901234567890123456789012" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.15, 0.25, 0.35, 0.45, 0.55],
    "top_k": 5,
    "namespace": "default"
  }' | jq

Expected Response:

{
  "matches": [
    {
      "id": "product-002",
      "score": 0.9998,
      "values": [0.2, 0.3, 0.4, 0.5, 0.6],
      "metadata": {
        "category": "electronics",
        "price": 399.99,
        "brand": "GadgetInc"
      }
    },
    {
      "id": "product-001",
      "score": 0.9985,
      "values": [0.1, 0.2, 0.3, 0.4, 0.5],
      "metadata": {
        "category": "electronics",
        "price": 299.99,
        "brand": "TechCo"
      }
    }
  ],
  "namespace": "default"
}

4. Fetch Vectors by ID

curl -X GET "http://localhost:8080/pinecone/vectors/fetch?ids=product-001,product-002" \
  -H "x-api-key: 12345678901234567890123456789012" | jq

Expected Response:

{
  "vectors": {
    "product-001": {
      "id": "product-001",
      "values": [0.1, 0.2, 0.3, 0.4, 0.5],
      "metadata": {
        "category": "electronics",
        "price": 299.99,
        "brand": "TechCo"
      }
    },
    "product-002": {
      "id": "product-002",
      "values": [0.2, 0.3, 0.4, 0.5, 0.6],
      "metadata": {
        "category": "electronics",
        "price": 399.99,
        "brand": "GadgetInc"
      }
    }
  }
}

5. Delete Vectors

curl -X DELETE http://localhost:8080/pinecone/vectors/delete \
  -H "x-api-key: 12345678901234567890123456789012" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["product-001", "product-002"]
  }' | jq

Expected Response:

{
  "deleted_count": 2
}

Error Handling Tests

1. Unauthorized Request (Missing Auth)

curl -X POST http://localhost:8080/snowflake/session \
  -H "Content-Type: application/json" \
  -d '{"database":"test","schema":"public","warehouse":"wh","role":"user"}' | jq

Expected Response (401):

{
  "error": "Missing authorization header",
  "code": "UNAUTHORIZED"
}

2. Invalid Endpoint

curl -X GET http://localhost:8080/invalid/endpoint | jq

Expected Response (404):

{
  "error": "Unknown endpoint: /invalid/endpoint",
  "code": "NOT_FOUND"
}

3. Query Not Found

curl -X GET http://localhost:8080/snowflake/queries/nonexistent-id \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" | jq

Expected Response (404):

{
  "error": "Query not found: nonexistent-id",
  "code": "QUERY_NOT_FOUND"
}

Performance Testing

Concurrent Query Submission

# Submit 10 queries concurrently
for i in {1..10}; do
  curl -X POST http://localhost:8080/snowflake/queries \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" \
    -H "Content-Type: application/json" \
    -d "{\"sql\":\"SELECT $i\"}" &
done
wait

Load Testing with Apache Bench

# Install apache2-utils if needed: apt-get install apache2-utils

# Test Snowflake query submission
ab -n 1000 -c 10 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" \
  -H "Content-Type: application/json" \
  -p query.json \
  http://localhost:8080/snowflake/queries

# query.json content:
# {"sql":"SELECT 1"}

Integration Scripts

Full Snowflake Workflow

#!/bin/bash
set -e

JWT="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU"

# 1. Create session
echo "Creating session..."
SESSION=$(curl -s -X POST http://localhost:8080/snowflake/session \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"database":"db","schema":"public","warehouse":"wh","role":"user"}')
echo $SESSION | jq

# 2. Submit query
echo "Submitting query..."
QUERY_RESP=$(curl -s -X POST http://localhost:8080/snowflake/queries \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM users"}')
echo $QUERY_RESP | jq

QUERY_ID=$(echo $QUERY_RESP | jq -r '.query_id')

# 3. Poll status
echo "Polling status..."
for i in {1..5}; do
  STATUS=$(curl -s -X GET http://localhost:8080/snowflake/queries/$QUERY_ID \
    -H "Authorization: Bearer $JWT")
  echo $STATUS | jq
  sleep 0.05
done

# 4. Get results
echo "Fetching results..."
RESULT=$(curl -s -X GET http://localhost:8080/snowflake/queries/$QUERY_ID/result \
  -H "Authorization: Bearer $JWT")
echo $RESULT | jq

Troubleshooting

Server not responding

# Check if server is running
curl http://localhost:8080/health || echo "Server not running"

# Check server logs for errors
# Look for "HTTP Gateway listening on..." message

Authentication failures

# Verify JWT structure (should have 3 parts separated by dots)
echo "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9.dGVzdF9zaWduYXR1cmU" | tr '.' '\n' | wc -l
# Should output: 3

# Decode JWT payload (base64url decode second part)
echo "eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE2MDAwMDAwMDB9" | base64 -d | jq

Invalid JSON

# Validate JSON before sending
echo '{"sql":"SELECT 1"}' | jq . || echo "Invalid JSON"