Skip to content

API.md

Latest commit

 

History

History
530 lines (447 loc) · 10 KB

API.md

File metadata and controls

530 lines (447 loc) · 10 KB
Raw

FakeBank API Documentation

Comprehensive API reference for all FakeBank microservices.

⚠️ IMPORTANT: These APIs are for demonstration and data lineage testing only. DO NOT use in production.

Table of Contents

  1. Overview
  2. Authentication
  3. Security Service API
  4. Consumer Service API
  5. Accounts Service API
  6. Credit Rating Service API
  7. Risk Assessment Service API
  8. Error Handling
  9. Rate Limiting

Overview

All FakeBank services follow RESTful principles and use JSON for request/response bodies. Each service runs on a specific port:

Service Port Base URL
Security 3001 http://localhost:3001/api/v1
Consumer 3000 http://localhost:3000/api/v1
Accounts 3002 http://localhost:3002/api/v1
Credit Rating 3003 http://localhost:3003/api/v1
Risk Assessment 3009 http://localhost:3009/api/v1

Authentication

All services (except health endpoints) require JWT authentication. Tokens are obtained from the Security Service and must be included in the Authorization header:

Authorization: Bearer <jwt-token>

Token Structure

{
  "userId": "U-123-456-789",
  "username": "manager1",
  "role": "BRANCH_MANAGER",
  "iat": 1234567890,
  "exp": 1234571490
}

Roles and Permissions

Role Description Access Level
SUPERVISOR System administrator Full access
BRANCH_MANAGER Branch manager Create, update, approve
CUSTOMER_SERVICE Customer service agent Create, read
INFORMATION Analyst/Auditor Read-only

Security Service API

Authentication Endpoints

POST /api/v1/auth/login

Authenticate user and receive JWT token.

Request:

{
  "username": "manager1",
  "password": "Manager123!"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "U-123-456-789",
    "username": "manager1",
    "role": "BRANCH_MANAGER",
    "isActive": true,
    "lastLoginAt": "2024-01-15T10:30:00Z"
  }
}

POST /api/v1/auth/verify

Verify JWT token validity.

Request:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "valid": true,
  "user": {
    "userId": "U-123-456-789",
    "username": "manager1",
    "role": "BRANCH_MANAGER"
  }
}

POST /api/v1/auth/refresh

Refresh an existing token.

Request:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": "1h"
}

User Management Endpoints

GET /api/v1/users

List all users (requires SUPERVISOR role).

Response:

[
  {
    "id": "U-123-456-789",
    "username": "manager1",
    "role": "BRANCH_MANAGER",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "lastLoginAt": "2024-01-15T10:30:00Z"
  }
]

POST /api/v1/users

Create new user (requires SUPERVISOR role).

Request:

{
  "username": "newuser",
  "password": "SecurePass123!",
  "role": "CUSTOMER_SERVICE"
}

Consumer Service API

Customer Endpoints

GET /api/v1/customers

List all customers with pagination.

Query Parameters:

  • page (default: 1)
  • limit (default: 20)
  • includeDeleted (default: false)

Response:

{
  "data": [
    {
      "id": "C-123-456-789",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "555-123-4567",
      "address": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "ssn": "XXX-XX-6789",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

POST /api/v1/customers

Create new customer (requires editor role).

Request:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com",
  "phone": "555-987-6543",
  "address": "456 Oak Ave",
  "city": "Somewhere",
  "state": "NY",
  "zip": "54321",
  "ssn": "987-65-4321"
}

POST /api/v1/customers/search

Search customers (SSN search via POST only).

Request:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john",
  "ssn": "123-45-6789"
}

Accounts Service API

Account Endpoints

GET /api/v1/accounts

List all accounts.

Query Parameters:

  • page (default: 1)
  • limit (default: 50)
  • status (ACTIVE, CLOSED, SUSPENDED, PENDING)
  • accountType (credit, checking, savings, ira, 401k, mortgage)

Response:

{
  "data": [
    {
      "id": "ACC-123-456-789",
      "consumerId": "C-123-456-789",
      "accountNumber": "1234567890",
      "accountType": "checking",
      "status": "ACTIVE",
      "metadata": {
        "accountSubtype": "checking",
        "overdraftProtection": true
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 500
  }
}

POST /api/v1/accounts

Create new account (requires BRANCH_MANAGER role).

Request:

{
  "consumerId": "C-123-456-789",
  "accountType": "checking",
  "metadata": {
    "accountSubtype": "checking",
    "overdraftProtection": true,
    "minimumBalance": 100,
    "monthlyFee": 10
  }
}

GET /api/v1/accounts/:id/history

Get account snapshot history.

Query Parameters:

  • startDate (ISO 8601 format)
  • endDate (ISO 8601 format)
  • limit (default: 24)

Response:

{
  "accountId": "ACC-123-456-789",
  "snapshots": [
    {
      "id": "SNAP-123-456-789",
      "statementDate": "2024-01-15",
      "balances": {
        "current": 5000.00,
        "available": 4500.00,
        "pending": 500.00
      },
      "transactionCount": 45,
      "status": "ACTIVE"
    }
  ]
}

Credit Rating Service API

Credit Report Endpoints

POST /api/v1/credit-report/soft

Perform soft credit inquiry (no inquiry recorded).

Request:

{
  "ssn": "123-45-6789",
  "requestReason": "ACCOUNT_REVIEW"
}

Response:

{
  "consumerId": "CR-123-456-789",
  "creditScore": 720,
  "scoreFactors": [
    "Good payment history",
    "Low credit utilization",
    "Long credit history"
  ],
  "accounts": [
    {
      "creditor": "Bank of Example",
      "accountType": "CREDIT_CARD",
      "balance": 1500,
      "creditLimit": 10000,
      "paymentStatus": "CURRENT",
      "monthsReviewed": 24
    }
  ],
  "publicRecords": [],
  "inquiries": []
}

POST /api/v1/credit-report/hard

Perform hard credit inquiry (inquiry recorded).

Request:

{
  "ssn": "123-45-6789",
  "requestReason": "NEW_CREDIT",
  "creditorName": "FakeBank"
}

Search Endpoints

POST /api/v1/search

Search consumers by name.

Request:

{
  "firstName": "John",
  "lastName": "Doe"
}

Response:

{
  "results": [
    {
      "consumerId": "CR-123-456-789",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-01",
      "lastAddress": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      }
    }
  ]
}

Risk Assessment Service API

Assessment Endpoints

POST /api/v1/risk-assessments

Create new risk assessment.

Request:

{
  "consumerId": "C-123-456-789",
  "productType": "LOAN",
  "requestedAmount": 25000,
  "requestedTermMonths": 60
}

Response:

{
  "id": "RA-123-456-789",
  "consumerId": "C-123-456-789",
  "productType": "LOAN",
  "riskScore": 72,
  "riskLevel": "MEDIUM",
  "factors": {
    "creditScore": 680,
    "creditScoreWeight": 0.35,
    "paymentHistory": 0.85,
    "paymentHistoryWeight": 0.25,
    "creditUtilization": 0.45,
    "utilizationWeight": 0.20,
    "debtToIncomeRatio": 0.38,
    "dtiWeight": 0.15,
    "recentInquiries": 2,
    "inquiriesWeight": 0.05
  },
  "recommendations": [
    "Consider requesting additional collateral",
    "Verify employment and income documentation"
  ],
  "assessmentDate": "2024-01-15T10:30:00Z",
  "expiryDate": "2024-04-15T10:30:00Z"
}

GET /api/v1/risk-assessments/consumer/:consumerId/latest

Get most recent assessment for a consumer.

GET /api/v1/risk-assessments/consumer/:consumerId/history

Get assessment history.

Query Parameters:

  • days (default: 90)

Error Handling

All services use consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/v1/customers"
}

Common Error Codes

Code HTTP Status Description
UNAUTHORIZED 401 Missing or invalid authentication
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
VALIDATION_ERROR 400 Invalid request data
DUPLICATE_ENTRY 409 Resource already exists
RATE_LIMIT_EXCEEDED 429 Too many requests
INTERNAL_ERROR 500 Server error

Rate Limiting

Services implement rate limiting to prevent abuse:

  • Security Service: 5 login attempts per minute
  • Consumer Service: 100 requests per minute per API key
  • Other Services: 1000 requests per minute per authenticated user

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

Health Check Endpoints

All services provide health check endpoints (no authentication required):

GET /health
GET /api/v1/health

Response:

{
  "status": "healthy",
  "service": "accounts",
  "timestamp": "2024-01-15T10:30:00Z",
  "uptime": 3600,
  "version": "1.0.0",
  "dependencies": {
    "database": "connected",
    "consumerService": "reachable",
    "securityService": "reachable"
  }
}

For service-specific API documentation, see individual service README files.