REST API Endpoints Reference

Complete reference for all REST API endpoints in the Personal Finance Platform.

API Overview 

Base URL 

All API endpoints are prefixed with:

http://localhost:8000/api/

Authentication 

The API supports multiple authentication methods:

Session Authentication: For web interface integration
Token Authentication: For programmatic access
API Key Authentication: For service-to-service communication

# Token authentication
curl -H \"Authorization: Token your-token-here\" http://localhost:8000/api/

Response Format 

All API responses follow this structure:

{
    \"results\": [...],     // For list endpoints
    \"count\": 100,         // Total count for paginated results
    \"next\": \"url\",        // Next page URL
    \"previous\": \"url\"     // Previous page URL
}

Error responses:

{
    \"error\": \"error_code\",
    \"message\": \"Human readable error message\",
    \"details\": {...}      // Additional error context
}

Pagination 

List endpoints support pagination:

Limit: ?limit=50 (default: 20, max: 100)
Offset: ?offset=20
Page: ?page=2 (alternative to offset)

Portfolio Management 

Portfolio Endpoints 

Position Management 

Transaction Management 

Asset Management 

Asset Endpoints 

Market Data 

Backtesting API 

Strategy Management 

Backtest Execution 

Analytics API 

Portfolio Analytics 

Risk Analytics 

Tax API 

Tax Calculations 

Tax Loss Harvesting 

Tax Reports 

Real-time API 

WebSocket Information 

Service Status 

Force Updates 

Error Handling 

HTTP Status Codes 

200 OK - Successful request
201 Created - Resource created successfully
204 No Content - Successful request with no response body
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format 

{
    \"error\": \"validation_error\",
    \"message\": \"Invalid portfolio ID\",
    \"details\": {
        \"field\": \"portfolio_id\",
        \"code\": \"invalid_choice\"
    }
}

Rate Limiting 

API endpoints are rate limited:

Authenticated users: 1000 requests/hour
Anonymous users: 100 requests/hour
Real-time endpoints: 10 requests/minute

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

API Client Examples 

Python Client 

import requests

class FinanceAPIClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Token {token}'}

    def get_portfolios(self):
        response = requests.get(
            f'{self.base_url}/api/portfolios/',
            headers=self.headers
        )
        return response.json()

    def create_transaction(self, transaction_data):
        response = requests.post(
            f'{self.base_url}/api/transactions/',
            json=transaction_data,
            headers=self.headers
        )
        return response.json()

    def run_backtest(self, strategy_id, backtest_config):
        # Create backtest
        backtest_data = {
            'strategy': strategy_id,
            **backtest_config
        }
        response = requests.post(
            f'{self.base_url}/api/backtesting/backtests/',
            json=backtest_data,
            headers=self.headers
        )
        backtest = response.json()

        # Run backtest
        response = requests.post(
            f'{self.base_url}/api/backtesting/backtests/{backtest[\"id\"]}/run/',
            headers=self.headers
        )
        return response.json()

JavaScript Client 

class FinanceAPIClient {
    constructor(baseUrl, token) {
        this.baseUrl = baseUrl;
        this.headers = {
            'Authorization': `Token ${token}`,
            'Content-Type': 'application/json'
        };
    }

    async getPortfolios() {
        const response = await fetch(`${this.baseUrl}/api/portfolios/`, {
            headers: this.headers
        });
        return response.json();
    }

    async getPortfolioMetrics(portfolioId, period = '1y') {
        const response = await fetch(
            `${this.baseUrl}/api/analytics/portfolio/${portfolioId}/metrics/?period=${period}`,
            { headers: this.headers }
        );
        return response.json();
    }

    async createTransaction(transactionData) {
        const response = await fetch(`${this.baseUrl}/api/transactions/`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(transactionData)
        });
        return response.json();
    }
}