Skip to content

endpoints.md

Latest commit

 

History

History
522 lines (392 loc) · 10.9 KB

endpoints.md

File metadata and controls

522 lines (392 loc) · 10.9 KB
Raw

REST API Endpoints

Base URL

Development: http://localhost:8000
Production: https://isc-codeconnect.ibm.com

Authentication

The system uses IBM OIDC (OpenID Connect) authentication with session-based management:

Session-Based Authentication

After successful OIDC login, user sessions are managed via secure cookies. GitHub integration uses session-stored tokens.

Core Endpoints

System Health & Status

GET /api/health

System health check and configuration status.

Response:

{
  "status": "healthy",
  "message": "API is running",
  "assistant_status": "initialized",
  "frontend_url": "http://localhost:3000",
  "heartbeat_enabled": true,
  "heartbeat_type": "simple_comments",
  "heartbeat_interval": "30 seconds",
  "timeout_protection": "enabled",
  "cirrus_compatible": true,
  "model_support": {
    "dynamic_model_selection": true,
    "current_model": "ibm/granite-3-8b-instruct",
    "model_source": "frontend_request_or_env_default"
  }
}

GET /api/models

Get available LLM models for dynamic selection.

Response:

{
  "status": "success",
  "current_model": "ibm/granite-3-8b-instruct",
  "available_models": [
    "ibm/granite-3-2-8b-instruct",
    "ibm/granite-3-8b-instruct",
    "ibm/granite-3.3-8b-instruct",
    "meta-llama/llama-3-70b-instruct",
    "mistralai/mixtral-8x7b-instruct-v01"
  ],
  "common_models": ["ibm/granite-3-8b-instruct"],
  "message": "Use 'selectedModel' field in query requests to specify model"
}

Chat & Query Processing

POST /api/query

Send a message to the multi-agent Salesforce RAG system.

Request Body:

{
  "query": "Create an Apex class for handling Account operations",
  "user_info": {
    "name": "john.doe@ibm.com",
    "session_id": "uuid-session-id"
  },
  "selectedModel": "ibm/granite-3-8b-instruct"
}

Response:

{
  "response": "I'll help you create an Apex class for Account operations...",
  "metrics": {
    "cache_hits": 3,
    "cache_misses": 1,
    "parallel_operations": 5,
    "average_processing_time": 2.3,
    "execution_time": 2.3,
    "start_time": "2025-07-03 10:00:00.123456",
    "end_time": "2025-07-03 10:00:02.456789"
  }
}

POST /api/query/stream

Stream a query response with heartbeat protection for long-running queries.

Request Body: Same as /api/query

Response: Server-Sent Events (SSE) stream

Content-Type: text/event-stream
X-Heartbeat-Enabled: simple

data: {"content": "I'll help you create...", "done": false}

data: {"content": "an Apex class for Account operations", "done": false}

: heartbeat - keeping connection alive

data: {"content": "Final response content", "done": true}

GET /api/stream/test

Test endpoint for streaming with configurable heartbeat mechanism.

Query Parameters:

  • duration: Test duration in seconds (default: 240)
  • interval: Time between messages (default: 45s)
  • heartbeat_interval: Heartbeat interval (default: 30s)

Chat Session Management

POST /api/chat/new

Start a new chat session.

Request Body:

{
  "username": "john.doe@ibm.com",
  "session_id": "uuid-session-id"
}

Response:

{
  "status": "success",
  "message": "New chat session started",
  "session_id": "uuid-session-id"
}

POST /api/chat/reset

Reset the chat state and clear conversation history.

Request Body:

{
  "username": "john.doe@ibm.com",
  "session_id": "uuid-session-id"
}

Response:

{
  "status": "success",
  "message": "Chat state reset successfully"
}

GitHub Integration

GET /api/github/health

Health check for GitHub integration with session-based token support.

Query Parameters:

  • github_token: Optional GitHub token (falls back to session or environment)

Response:

{
  "status": "healthy",
  "github_api_accessible": true,
  "authentication_method": "session-based",
  "rate_limit": {
    "remaining": 4500,
    "reset_time": "2025-07-03T11:00:00Z"
  },
  "repository_access": "verified"
}

POST /api/github/query

Query GitHub repositories with AI-powered analysis.

Request Body:

{
  "query": "How does the authentication system work in this repository?",
  "orgName": "IBM",
  "repository": "salesforce-toolkit",
  "user_info": {
    "name": "john.doe@ibm.com",
    "session_id": "uuid-session-id",
    "email": "john.doe@ibm.com"
  },
  "github_token": "optional-token",
  "messages": [
    {
      "role": "user",
      "content": "Previous question"
    },
    {
      "role": "assistant",
      "content": "Previous answer"
    }
  ],
  "contextTypes": ["code", "documentation"]
}

Response:

{
  "answer": "The authentication system in this repository uses...",
  "tools_used": ["github_file_reader", "github_search"],
  "raw_data": {
    "files_analyzed": ["src/auth/index.js", "README.md"],
    "search_results": 15
  },
  "metrics": {
    "cache_hits": 0,
    "cache_misses": 1,
    "parallel_operations": 1,
    "average_processing_time": 3.2,
    "execution_time": 3.2,
    "start_time": "2025-07-03 10:00:00.123456",
    "end_time": "2025-07-03 10:00:03.345678"
  },
  "messages": [
    {
      "role": "user",
      "content": "How does the authentication system work?"
    },
    {
      "role": "assistant",
      "content": "The authentication system..."
    }
  ]
}

POST /api/github/query/stream

Stream GitHub repository analysis with heartbeat protection.

Request Body: Same as /api/github/query

Response: Server-Sent Events (SSE) stream with GitHub analysis progress.

GET /api/github/repository/{org_name}/{repo_name}/summary

Get a quick summary of a GitHub repository.

Path Parameters:

  • org_name: Organization name
  • repo_name: Repository name

Query Parameters:

  • github_token: Optional GitHub token

Response:

{
  "org_name": "IBM",
  "repo_name": "salesforce-toolkit",
  "summary": {
    "description": "A comprehensive toolkit for Salesforce development",
    "primary_language": "JavaScript",
    "languages": ["JavaScript", "Apex", "HTML"],
    "file_count": 245,
    "main_directories": ["src", "docs", "tests"],
    "recent_activity": "Active development"
  },
  "timestamp": "2025-07-03T10:40:00Z",
  "authentication": "session-based"
}

POST /api/github/store-token

Store GitHub token in user session for authentication.

Request Body:

{
  "github_token": "ghp_xxxxxxxxxxxxxxxxxxxx"
}

Response:

{
  "status": "success",
  "message": "GitHub token stored successfully in session",
  "token_validation": "valid",
  "authentication_method": "session-based"
}

DELETE /api/github/remove-token

Remove GitHub token from user session.

Response:

{
  "status": "success",
  "message": "GitHub token removed from session"
}

POST /api/github/reset-chat

Reset GitHub chat history for a specific repository.

Request Body:

{
  "username": "john.doe@ibm.com",
  "session_id": "uuid-session-id",
  "org_name": "IBM",
  "repo_name": "salesforce-toolkit",
  "github_token": "optional-token"
}

Response:

{
  "status": "success",
  "message": "GitHub chat history reset successfully"
}

Error Responses

Standard Error Format

{
  "detail": {
    "message": "Assistant not initialized",
    "location": "process_query",
    "details": null
  }
}

Common HTTP Status Codes

  • 401 Unauthorized: User not authenticated or invalid GitHub token
  • 403 Forbidden: User not authorized (not in required group or organization)
  • 500 Internal Server Error: System error with detailed error response
  • 503 Service Unavailable: Assistant not initialized

Authentication & Authorization

GET /login

Initiate OIDC authentication flow.

Response: Redirects to IBM OIDC authorization server.

GET /redirect

OAuth2 callback to process authorization code and fetch user information.

Query Parameters:

  • code: Authorization code from OIDC provider

Response:

  • Success: Redirects to frontend with session established
  • Error: JSON error response with 403 status for unauthorized users

Requirement Analysis (Additional Module)

POST /api/requirement-analyzer/analyze

Analyze software requirements and break them down into implementation tasks.

Request Body:

{
  "requirement": "Create a customer management system with CRUD operations",
  "supporting_docs": [
    {
      "content": "Additional requirements document content",
      "name": "requirements.md"
    }
  ],
  "user_info": {
    "name": "john.doe@ibm.com",
    "session_id": "uuid-session-id"
  }
}

Response:

{
  "analysis": {
    "requirement_summary": "Build a customer management system with full CRUD capabilities",
    "key_components": [
      "Customer data model",
      "CRUD API endpoints",
      "User interface"
    ],
    "tasks": [
      {
        "task_id": 1,
        "title": "Create Customer Data Model",
        "description": "Design and implement customer entity with required fields",
        "affected_files": ["models/Customer.cls"],
        "implementation_details": "Create Apex class with proper field definitions...",
        "references": ["Salesforce Object Guidelines"],
        "estimated_complexity": "Medium"
      }
    ],
    "missing_information": ["Specific field requirements for customer entity"],
    "assumptions": ["Using Salesforce platform for implementation"]
  },
  "metrics": {
    "processing_time": 1.8,
    "tasks_generated": 5,
    "complexity_distribution": {
      "Low": 2,
      "Medium": 2,
      "High": 1
    }
  }
}

POST /api/requirement-analyzer/analyze/stream

Stream requirement analysis with real-time progress updates.

Request Body: Same as analyze endpoint

Response: Server-Sent Events stream with analysis progress.

Streaming Protocol

Server-Sent Events (SSE)

All streaming endpoints use SSE format with heartbeat protection:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Heartbeat-Enabled: simple

data: {"content": "Response chunk", "done": false}

: heartbeat - keeping connection alive

data: {"content": "Final chunk", "done": true}

Heartbeat Mechanism

  • Simple Comments: Sends : heartbeat comments every 30 seconds
  • No Frontend Changes Required: Compatible with standard SSE implementations
  • Timeout Protection: Prevents proxy/load balancer timeouts during long processing

Session Management

Session-Based Authentication

  • OIDC authentication creates secure session cookies
  • GitHub tokens stored in user sessions for repository access
  • Thread IDs generated from username_sessionId for conversation continuity
  • Chat history maintained per repository in GitHub integration

Thread Management

  • Salesforce RAG: {username}_{session_id}
  • GitHub Integration: {username}_{session_id}_{org_name}_{repo_name}
  • Conversation history limited to last 20 messages for performance