Skip to content

API.md

Latest commit

 

History

History
249 lines (190 loc) · 4.76 KB

API.md

File metadata and controls

249 lines (190 loc) · 4.76 KB
Raw

API Documentation

The Graph Visualization tool provides a REST API for programmatic access to neighbourhood data.

Base URL

http://localhost:5000

Endpoints

GET /

Returns the main visualization interface (HTML page).

Response: HTML page

GET /api/queries

Get a list of all available queries.

Response:

[
  {
    "qid": "0",
    "query": "what is the capital of france"
  },
  {
    "qid": "1",
    "query": "how do airplanes fly"
  }
]

GET /api/neighbourhood/<qid>

Get neighbourhood data for a specific query.

Parameters:

  • num_rows (optional, default: 100) - Number of document rows to return
  • num_columns (optional, default: 16) - Number of neighbour columns to return

Example:

GET /api/neighbourhood/0?num_rows=50&num_columns=10

Response:

{
  "qid": "0",
  "query": "what is the capital of france",
  "neighbourhood": [
    ["doc1", "doc2", "doc3", ...],
    ["doc4", "doc5", "doc6", ...],
    ...
  ],
  "relevance": [
    [0, 3, 0, ...],
    [1, 0, 2, ...],
    ...
  ],
  "num_rows": 50,
  "num_columns": 10,
  "stats": {
    "original_recall": 0.667,
    "neighbour_recall": 0.333,
    "total_recall": 0.833
  }
}

Relevance Labels:

  • 0 - Not relevant
  • 1 - Relevant (in original ranking)
  • 2 - Duplicate relevant document
  • 3 - New relevant document

GET /api/document/<docno>

Get details about a specific document.

Example:

GET /api/document/doc123

Response:

{
  "docno": "doc123",
  "qrels": [
    {
      "qid": "0",
      "docno": "doc123",
      "label": 1
    }
  ]
}

GET /api/debug/<qid>

Debug endpoint to inspect data matching (for development).

Response:

{
  "qid": "0",
  "sample_neighbourhood_docnos": ["doc1", "doc2", "doc3"],
  "qrels_count": 5,
  "sample_qrels_docnos": ["doc1", "doc4", "doc5"],
  "matches": [
    {
      "docno": "doc1",
      "docno_repr": "'doc1'",
      "docno_len": 4,
      "match_found": true,
      "match_data": [{"qid": "0", "docno": "doc1", "label": 1}]
    }
  ]
}

Python Client Example

import requests

# Base URL
base_url = "http://localhost:5000"


# Get all queries
response = requests.get(f"{base_url}/api/queries")
queries = response.json()
print(f"Found {len(queries)} queries")

# Get neighbourhood for first query
qid = queries[0]['qid']
response = requests.get(
    f"{base_url}/api/neighbourhood/{qid}",
    params={"num_rows": 100, "num_columns": 16}
)
data = response.json()

print(f"Query: {data['query']}")
print(f"Original Recall: {data['stats']['original_recall']:.3f}")
print(f"Total Recall: {data['stats']['total_recall']:.3f}")

# Count relevant documents by type
import numpy as np
relevance = np.array(data['relevance'])
print(f"Not relevant: {np.sum(relevance == 0)}")
print(f"Relevant (original): {np.sum(relevance == 1)}")
print(f"Duplicate relevant: {np.sum(relevance == 2)}")
print(f"New relevant: {np.sum(relevance == 3)}")

JavaScript Client Example

// Fetch all queries
fetch('/api/queries')
  .then(response => response.json())
  .then(queries => {
    console.log(`Found ${queries.length} queries`);
    
    // Get neighbourhood for first query
    const qid = queries[0].qid;
    return fetch(`/api/neighbourhood/${qid}?num_rows=100&num_columns=16`);
  })
  .then(response => response.json())
  .then(data => {
    console.log('Query:', data.query);
    console.log('Original Recall:', data.stats.original_recall);
    console.log('Total Recall:', data.stats.total_recall);
    
    // Count new relevant documents
    const newRelevant = data.relevance.flat().filter(x => x === 3).length;
    console.log('New relevant documents:', newRelevant);
  });

Error Responses

All endpoints return standard HTTP status codes:

  • 200 OK - Request successful
  • 400 Bad Request - Invalid parameters
  • 404 Not Found - Query or document not found
  • 500 Internal Server Error - Server error

Error response format:

{
  "error": "Error message describing what went wrong"
}

Rate Limiting

Currently, no rate limiting is implemented. For production use, consider adding rate limiting middleware.

CORS

By default, CORS is not enabled. To enable CORS for cross-origin requests:

from flask_cors import CORS

app = Flask(__name__)
CORS(app)  # Enable CORS for all routes

Authentication

No authentication is required by default. For production deployments, consider adding authentication:

from flask_httpauth import HTTPBasicAuth

auth = HTTPBasicAuth()

@auth.verify_password
def verify_password(username, password):
    # Verify credentials
    return username == "admin" and password == "secret"

@app.route('/api/queries')
@auth.login_required
def get_queries():
    # Protected endpoint
    pass