dbis_core/docs/api-guide.md

DBIS Core Banking System - API Documentation Guide

This guide provides comprehensive API documentation standards, best practices, and examples for the DBIS Core Banking System.

API Architecture

graph TB
    subgraph "Client Layer"
        WEB[Web Clients]
        MOBILE[Mobile Apps]
        PARTNER[Partner Systems]
        INTERNAL[Internal Services]
    end
    
    subgraph "API Gateway"
        GATEWAY[API Gateway]
        AUTH[Authentication]
        RATE[Rate Limiting]
        ROUTING[Request Routing]
    end
    
    subgraph "Service Layer"
        PAYMENT[Payment Service]
        FX[FX Service]
        CBDC[CBDC Service]
        LEDGER[Ledger Service]
    end
    
    subgraph "Data Layer"
        DB[(Database)]
        CACHE[(Cache)]
        HSM[HSM]
    end
    
    WEB --> GATEWAY
    MOBILE --> GATEWAY
    PARTNER --> GATEWAY
    INTERNAL --> GATEWAY
    
    GATEWAY --> AUTH
    AUTH --> RATE
    RATE --> ROUTING
    
    ROUTING --> PAYMENT
    ROUTING --> FX
    ROUTING --> CBDC
    ROUTING --> LEDGER
    
    PAYMENT --> DB
    FX --> DB
    CBDC --> DB
    LEDGER --> DB
    
    PAYMENT --> CACHE
    FX --> CACHE
    CBDC --> CACHE
    
    PAYMENT --> HSM
    FX --> HSM
    CBDC --> HSM
    LEDGER --> HSM

API Request Flow

sequenceDiagram
    participant Client
    participant Gateway as API Gateway
    participant Auth as Auth Service
    participant Service as Business Service
    participant DB as Database
    participant HSM
    
    Client->>Gateway: HTTP Request
    Gateway->>Gateway: Validate Request Format
    Gateway->>Auth: Authenticate Request
    Auth->>HSM: Verify Signature
    HSM-->>Auth: Signature Valid
    Auth->>Auth: Check Permissions
    Auth-->>Gateway: Authorized
    Gateway->>Gateway: Apply Rate Limiting
    Gateway->>Service: Route Request
    Service->>DB: Query Data
    DB-->>Service: Return Data
    Service->>Service: Process Business Logic
    Service-->>Gateway: Response
    Gateway-->>Client: HTTP Response

API Design Principles

RESTful Design

1. Resource-Based URLs

   • Use nouns, not verbs
   • Use plural nouns for collections
   • Use hierarchical structure

2. HTTP Methods

   • GET: Retrieve resources
   • POST: Create resources
   • PUT: Update resources (full)
   • PATCH: Update resources (partial)
   • DELETE: Delete resources

3. Status Codes

   • 200: Success
   • 201: Created
   • 400: Bad Request
   • 401: Unauthorized
   • 403: Forbidden
   • 404: Not Found
   • 500: Internal Server Error

Request/Response Format

Request Headers

Authorization: Bearer <jwt_token>
Content-Type: application/json
X-Request-ID: <correlation_id>
X-Signature: <request_signature>
X-Timestamp: <unix_timestamp>

Response Format

{
  "success": true,
  "data": {
    // Response data
  },
  "metadata": {
    "requestId": "req_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance in source account",
    "details": {
      "accountId": "acc_123",
      "availableBalance": 100.00,
      "requestedAmount": 200.00
    }
  },
  "metadata": {
    "requestId": "req_123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Authentication & Authorization

Authentication Flow

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant Auth as Auth Service
    participant HSM
    
    Client->>API: Request with Credentials
    API->>Auth: Validate Credentials
    Auth->>HSM: Generate/Verify Token
    HSM-->>Auth: Token
    Auth-->>API: JWT Token
    API-->>Client: Return JWT Token
    
    Client->>API: Request with JWT Token
    API->>Auth: Validate JWT
    Auth->>HSM: Verify Signature
    HSM-->>Auth: Valid
    Auth-->>API: Authorized
    API->>API: Process Request

Authorization

1. Role-Based Access Control (RBAC)

   • Define roles (admin, operator, viewer)
   • Assign permissions to roles
   • Check permissions on each request

2. Resource-Based Authorization

   • Check ownership
   • Verify access rights
   • Validate business rules

Rate Limiting

Rate Limiting Strategy

graph TD
    subgraph "Rate Limiting Tiers"
        TIER1[Tier 1: Critical Endpoints<br/>100 req/min]
        TIER2[Tier 2: Standard Endpoints<br/>1000 req/min]
        TIER3[Tier 3: Read-Only Endpoints<br/>10000 req/min]
    end
    
    TIER1 --> ENFORCE[Rate Limiter]
    TIER2 --> ENFORCE
    TIER3 --> ENFORCE
    
    ENFORCE --> ALLOW[Allow Request]
    ENFORCE --> REJECT[Reject Request<br/>429 Too Many Requests]

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642248000

API Versioning

Versioning Strategy

graph LR
    subgraph "Versioning Approaches"
        URL[URL Versioning<br/>/api/v1/payments]
        HEADER[Header Versioning<br/>Accept: application/vnd.dbis.v1+json]
        QUERY[Query Versioning<br/>?version=1]
    end
    
    URL --> RECOMMENDED[Recommended]
    HEADER --> ALTERNATIVE[Alternative]
    QUERY --> NOT_RECOMMENDED[Not Recommended]

Version Lifecycle

1. Current Version: Actively maintained
2. Deprecated Version: Still supported, migration recommended
3. Retired Version: No longer supported

Error Handling

Error Categories

graph TD
    subgraph "Error Types"
        CLIENT[Client Errors<br/>4xx]
        SERVER[Server Errors<br/>5xx]
        BUSINESS[Business Logic Errors]
    end
    
    CLIENT --> VALIDATION[Validation Errors]
    CLIENT --> AUTH[Authentication Errors]
    CLIENT --> PERM[Permission Errors]
    
    SERVER --> INTERNAL[Internal Server Errors]
    SERVER --> TIMEOUT[Timeout Errors]
    SERVER --> UNAVAILABLE[Service Unavailable]
    
    BUSINESS --> INSUFFICIENT[Insufficient Balance]
    BUSINESS --> INVALID[Invalid State]
    BUSINESS --> CONFLICT[Business Rule Conflicts]

Error Response Codes

Code	Category	Description
400	Client Error	Bad Request
401	Client Error	Unauthorized
403	Client Error	Forbidden
404	Client Error	Not Found
409	Client Error	Conflict
429	Client Error	Too Many Requests
500	Server Error	Internal Server Error
503	Server Error	Service Unavailable

API Documentation Standards

OpenAPI/Swagger Specification

All APIs should be documented using OpenAPI 3.0 specification:

openapi: 3.0.0
info:
  title: DBIS Core Banking API
  version: 1.0.0
  description: Sovereign-grade financial infrastructure API
paths:
  /api/v1/payments:
    post:
      summary: Create a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '201':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

Documentation Requirements

1. Endpoint Documentation

   • Description
   • Request/response schemas
   • Example requests/responses
   • Error responses
   • Authentication requirements

2. Schema Documentation

   • Field descriptions
   • Data types
   • Validation rules
   • Example values

3. Authentication Documentation

   • Authentication methods
   • Token generation
   • Token usage
   • Permission requirements

Best Practices

API Design

1. Consistency

   • Use consistent naming conventions
   • Follow RESTful principles
   • Standardize error responses

2. Idempotency

   • Use idempotency keys
   • Support idempotent operations
   • Return same response for duplicate requests

3. Pagination

   • Use cursor-based pagination
   • Limit page size
   • Provide pagination metadata

4. Filtering & Sorting

   • Support filtering by common fields
   • Enable sorting by relevant fields
   • Document filter/sort options

Security

1. Input Validation

   • Validate all inputs
   • Use schema validation
   • Sanitize user inputs

2. Output Sanitization

   • Don't expose sensitive data
   • Mask sensitive fields
   • Use appropriate content types

3. HTTPS Only

   • Enforce HTTPS
   • Use TLS 1.3
   • Implement HSTS

Performance

1. Caching

   • Cache GET requests
   • Use appropriate cache headers
   • Implement cache invalidation

2. Compression

   • Use gzip compression
   • Compress large responses
   • Support content negotiation

3. Async Operations

   • Use async for long operations
   • Provide status endpoints
   • Support webhooks

API Testing

Testing Strategy

graph TD
    subgraph "API Testing"
        UNIT[Unit Tests]
        INT[Integration Tests]
        E2E[E2E Tests]
        LOAD[Load Tests]
        SEC[Security Tests]
    end
    
    UNIT --> COVERAGE[Test Coverage]
    INT --> COVERAGE
    E2E --> COVERAGE
    LOAD --> PERFORMANCE[Performance Validation]
    SEC --> SECURITY[Security Validation]

Test Examples

1. Happy Path Tests

   • Valid requests
   • Successful responses
   • Expected behavior

2. Error Scenarios

   • Invalid inputs
   • Authentication failures
   • Business rule violations

3. Edge Cases

   • Boundary values
   • Null/empty inputs
   • Concurrent requests

Recommendations

Priority: High

1. API Documentation

   • Document all endpoints
   • Keep documentation up to date
   • Provide interactive examples

2. Versioning Strategy

   • Implement URL versioning
   • Maintain backward compatibility
   • Plan deprecation timelines

3. Error Handling

   • Standardize error responses
   • Provide meaningful error messages
   • Include error codes

4. Rate Limiting

   • Implement per-endpoint limits
   • Use sliding window algorithm
   • Provide rate limit headers

For detailed recommendations, see RECOMMENDATIONS.md.

---

Related Documentation

• Best Practices Guide
• Recommendations
• Development Guide
• Architecture Atlas