Oliver/contract-query
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
contract-query/API_TESTING_GUIDE.md
michael 82be78c7ae initial commit
2025-08-14 15:03:33 -05:00

15 KiB
Raw Blame History

Contract Analysis Tool - API Testing Guide

This guide provides comprehensive step-by-step instructions to test all APIs in the Contract Analysis Tool with real input examples.

Prerequisites

  1. Backend Server Running: http://localhost:8000
  2. Frontend Server Running: http://localhost:3000
  3. MongoDB Running: localhost:27017
  4. Redis Running: localhost:6379
  5. Environment Variables: Ensure .env files are properly configured

Authentication Setup

Step 1: Initialize Default Users

curl -X POST http://localhost:8000/api/v1/auth/init-users

Expected Response:

{
  "message": "Default users created successfully",
  "admin_email": "admin@oliver.agency",
  "user_email": "user@oliver.agency"
}

Step 2: Test Health Check

curl http://localhost:8000/health

Expected Response:

{
  "status": "healthy",
  "version": "2.0.0"
}

Authentication APIs

1. Admin Login

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@oliver.agency",
    "password": "admin123"
  }'

Expected Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "...",
    "email": "admin@oliver.agency",
    "role": "admin",
    "is_active": true,
    "index_access": [...]
  }
}

Save the admin token:

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

2. User Login

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@oliver.agency",
    "password": "user123"
  }'

Save the user token:

USER_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. Get Current User Info

curl -X GET http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Admin APIs

User Management

1. Get All Users

curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN"

2. Create New User

curl -X POST http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "testuser@example.com",
    "password": "SecurePass123",
    "role": "user",
    "is_active": true
  }'

Save the user ID from response:

NEW_USER_ID="686ec44005b0398525fde787"

3. Update User

curl -X PUT http://localhost:8000/api/v1/admin/users/$NEW_USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "updated_testuser@example.com",
    "role": "admin",
    "is_active": false
  }'

4. Delete User

curl -X DELETE http://localhost:8000/api/v1/admin/users/$NEW_USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Index Management

1. Get All Indices

curl -X GET http://localhost:8000/api/v1/admin/indices \
  -H "Authorization: Bearer $ADMIN_TOKEN"

2. Create New Index

curl -X POST http://localhost:8000/api/v1/admin/indices/create \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "name=Test Contract Index" \
  -F "description=Index for testing contract analysis" \
  -F "chunk_size=1000" \
  -F "chunk_overlap=200"

Save the index ID from response:

TEST_INDEX_ID="test-index-2025-07-09-abc123"

3. Delete Index

curl -X DELETE http://localhost:8000/api/v1/admin/indices/$TEST_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Document Management

1. Upload Single Document

curl -X POST http://localhost:8000/api/v1/admin/documents/upload-single \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "file=@/path/to/your/document.pdf" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "custom_name=Test Contract Document"

2. Upload Multiple Documents

curl -X POST http://localhost:8000/api/v1/admin/documents/upload-multiple \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "files=@/path/to/document1.pdf" \
  -F "files=@/path/to/document2.pdf" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "base_name=Contract Batch"

3. Get Index Documents

curl -X GET http://localhost:8000/api/v1/admin/documents/$TEST_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Save a document ID from response:

DOCUMENT_ID="686ebfa705b0398525fde785"

4. Reprocess Document

curl -X POST http://localhost:8000/api/v1/admin/documents/$DOCUMENT_ID/reprocess \
  -H "Authorization: Bearer $ADMIN_TOKEN"

5. Delete Document

curl -X DELETE http://localhost:8000/api/v1/admin/documents/$DOCUMENT_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Index Access Management

1. Grant Index Access to User

curl -X POST http://localhost:8000/api/v1/admin/users/$USER_ID/grant-index-access \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "'$TEST_INDEX_ID'"
  }'

2. Revoke Index Access from User

curl -X POST http://localhost:8000/api/v1/admin/users/$USER_ID/revoke-index-access \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "'$TEST_INDEX_ID'"
  }'

3. Grant All Indices Access

curl -X POST http://localhost:8000/api/v1/admin/grant-all-indices/$USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

System Monitoring

1. Get System Statistics

curl -X GET http://localhost:8000/api/v1/admin/stats \
  -H "Authorization: Bearer $ADMIN_TOKEN"

2. Get Processing Status

curl -X GET http://localhost:8000/api/v1/admin/documents/processing-status \
  -H "Authorization: Bearer $ADMIN_TOKEN"

3. Process Pending Documents

curl -X POST http://localhost:8000/api/v1/admin/documents/process-pending \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Admin RAG Query

curl -X POST http://localhost:8000/api/v1/admin/chat/query \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "query=What are the key terms of this contract?" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "top_k=5"

User APIs

Index Access

1. Get User's Indices

curl -X GET http://localhost:8000/api/v1/indices/ \
  -H "Authorization: Bearer $USER_TOKEN"

2. Get Specific Index

curl -X GET http://localhost:8000/api/v1/indices/$TEST_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"

3. Create User Index

curl -X POST http://localhost:8000/api/v1/indices/create \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Contract Index",
    "description": "Personal contract analysis index"
  }'

Document Operations

1. Upload Document to Index

curl -X POST http://localhost:8000/api/v1/documents/upload \
  -H "Authorization: Bearer $USER_TOKEN" \
  -F "file=@/path/to/contract.pdf" \
  -F "index_id=$USER_INDEX_ID"

2. Get Documents by Index

curl -X GET http://localhost:8000/api/v1/documents/index/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"

3. Get Document Details

curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID \
  -H "Authorization: Bearer $USER_TOKEN"

4. Get Document Summary (AI)

curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID/summary \
  -H "Authorization: Bearer $USER_TOKEN"

Expected Response:

{
  "document_id": "686ebfa705b0398525fde785",
  "filename": "Contract Document.pdf",
  "summary": "This document is a service agreement between...",
  "processing_status": "completed",
  "generated_at": "2025-07-09T19:41:12.301719"
}

5. Download Document

curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID/download \
  -H "Authorization: Bearer $USER_TOKEN" \
  --output downloaded_document.pdf

6. Delete Document

curl -X DELETE http://localhost:8000/api/v1/documents/$DOCUMENT_ID \
  -H "Authorization: Bearer $USER_TOKEN"

Chat and RAG

1. Query Documents (RAG)

curl -X POST http://localhost:8000/api/v1/chat/query \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the payment terms in this contract?",
    "index_id": "'$USER_INDEX_ID'",
    "top_k": 5
  }'

Expected Response:

{
  "response": "Based on the contract analysis, the payment terms include...",
  "cached": false,
  "response_time": 2.34,
  "debug_info": {
    "sources": [...],
    "context_used": true,
    "context_messages_count": 3
  }
}

2. Get Chat History

curl -X GET http://localhost:8000/api/v1/chat/history/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"

3. Clear Chat History

curl -X DELETE http://localhost:8000/api/v1/chat/history/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"

4. Get Index Chat Status

curl -X GET http://localhost:8000/api/v1/chat/status/$USER_INDEX_ID \
  -H "Authorization: Bearer $USER_TOKEN"

Permission Testing

Test User Access Restrictions

1. User Trying to Access Admin Endpoint (Should Fail)

curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $USER_TOKEN"

Expected Response:

{
  "detail": "Not enough permissions"
}

2. User Accessing Unauthorized Index (Should Fail)

curl -X GET http://localhost:8000/api/v1/documents/index/unauthorized-index-id \
  -H "Authorization: Bearer $USER_TOKEN"

3. Admin Accessing Any Resource (Should Work)

curl -X GET http://localhost:8000/api/v1/documents/index/$ANY_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Frontend Testing

1. Access Frontend

# Open browser to
http://localhost:3000

2. Test Login Flow

  1. Navigate to http://localhost:3000/login
  2. Login with admin credentials: admin@oliver.agency / admin123
  3. Verify dashboard access
  4. Check admin panel visibility in sidebar

3. Test Admin Panel

  1. Navigate to http://localhost:3000/dashboard/admin
  2. Test user management (create, edit, delete)
  3. Test index access management
  4. Verify system statistics

4. Test User Features

  1. Login as user: user@oliver.agency / user123
  2. Test document upload and management
  3. Test AI summary generation
  4. Test chat interface with documents

Error Testing

1. Invalid Authentication

curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer invalid_token"

2. Missing Required Fields

curl -X POST http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "incomplete@user.com"
  }'

3. Duplicate Email

curl -X POST http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@oliver.agency",
    "password": "test123",
    "role": "user"
  }'

Performance Testing

1. Large File Upload

curl -X POST http://localhost:8000/api/v1/documents/upload \
  -H "Authorization: Bearer $USER_TOKEN" \
  -F "file=@/path/to/large_document.pdf" \
  -F "index_id=$USER_INDEX_ID" \
  --max-time 300

2. Concurrent Chat Queries

# Run multiple queries simultaneously
for i in {1..5}; do
  curl -X POST http://localhost:8000/api/v1/chat/query \
    -H "Authorization: Bearer $USER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Query '$i': What is the contract about?",
      "index_id": "'$USER_INDEX_ID'"
    }' &
done
wait

Complete Test Workflow

1. Setup Test Environment

# Start services
cd /path/to/backend && uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 &
cd /path/to/frontend && npm run dev &

# Initialize users
curl -X POST http://localhost:8000/api/v1/auth/init-users

2. Login and Get Tokens

ADMIN_TOKEN=$(curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@oliver.agency", "password": "admin123"}' \
  | jq -r '.access_token')

USER_TOKEN=$(curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@oliver.agency", "password": "user123"}' \
  | jq -r '.access_token')

3. Create Test Index

INDEX_RESPONSE=$(curl -X POST http://localhost:8000/api/v1/admin/indices/create \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "name=API Test Index" \
  -F "description=Index for API testing")

TEST_INDEX_ID=$(echo $INDEX_RESPONSE | jq -r '.index_id')

4. Upload and Process Document

curl -X POST http://localhost:8000/api/v1/admin/documents/upload-single \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "file=@/path/to/test_contract.pdf" \
  -F "index_id=$TEST_INDEX_ID" \
  -F "custom_name=Test Contract"

5. Grant User Access

USER_ID=$(curl -X GET http://localhost:8000/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq -r '.[] | select(.email=="user@oliver.agency") | .id')

curl -X POST http://localhost:8000/api/v1/admin/users/$USER_ID/grant-index-access \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"index_id": "'$TEST_INDEX_ID'"}'

6. Test User Chat

curl -X POST http://localhost:8000/api/v1/chat/query \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize this contract",
    "index_id": "'$TEST_INDEX_ID'"
  }'

7. Test AI Summary

DOCUMENT_ID=$(curl -X GET http://localhost:8000/api/v1/admin/documents/$TEST_INDEX_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  | jq -r '.documents[0].id')

curl -X GET http://localhost:8000/api/v1/documents/$DOCUMENT_ID/summary \
  -H "Authorization: Bearer $USER_TOKEN"

Troubleshooting

Common Issues

  1. 401 Unauthorized: Check token validity and format
  2. 403 Forbidden: Verify user has required permissions
  3. 404 Not Found: Ensure resource exists and user has access
  4. 422 Validation Error: Check request body format and required fields
  5. 500 Internal Server Error: Check backend logs and OpenAI API key

Debug Commands

# Check backend logs
tail -f backend.log

# Check database connection
curl http://localhost:8000/health

# Verify token
curl -X GET http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

# Check OpenAI API key
echo $OPENAI_API_KEY

Notes

  • Replace /path/to/your/document.pdf with actual file paths
  • Replace placeholder IDs with actual IDs from responses
  • Ensure all environment variables are properly set
  • All timestamps are in UTC format
  • File uploads support PDF, DOCX, DOC, TXT, CSV, JSON, HTML, MD, RTF formats
  • Maximum file size is 50MB (configurable)