BMS Middleware API - API Documentation

📚 API Documentation

Interactive API Docs

Swagger UI with live testing

ReDoc

Clean, readable documentation

Health Check

API status and diagnostics

🔥 Key Features

Generic CRUD Operations - Insert, select, update any table dynamically
Auto-Mapping - Automatic dictionary to model conversion
Bulk Operations - Efficient batch inserts
Soft Delete - Data retention with deletion tracking
Audit Trail - Comprehensive change tracking
Production Ready - Azure SQL, Blob Storage, Cosmos DB compatible

🔌 Application Endpoints

POST /api/v1/applications

Create a new bursary application with auto-generated application number

GET /api/v1/applications

List all applications with optional filtering by status, pagination support

GET /api/v1/applications/{id}

Get a specific application by ID

PUT /api/v1/applications/{id}

Update an application (partial updates supported)

DELETE /api/v1/applications/{id}

Delete an application (soft delete by default)

⚡ Generic CRUD Endpoints

POST /api/v1/generic/insert NEW

Generic insert - dynamically insert into any table with auto-mapping

POST /api/v1/generic/select NEW

Generic select - query any table with dynamic columns and filters

PUT /api/v1/generic/update NEW

Generic update - update any record dynamically

POST /api/v1/generic/bulk-insert NEW

Bulk insert multiple records efficiently in a single transaction

💰 Payment Endpoints

POST /api/v1/payments

Create a new payment record with auto-generated payment reference

GET /api/v1/payments

List all payments with filtering by application_id or status

💡 Example Usage

Create Application

curl -X POST "http://localhost:8000/api/v1/applications" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+27821234567",
    "id_number": "9001015800080",
    "institution": "University of Johannesburg",
    "qualification": "BSc Computer Science",
    "year_of_study": 2,
    "average_grade": 75.5
  }'

Generic Insert

curl -X POST "http://localhost:8000/api/v1/generic/insert" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "applications",
    "data": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+27821234568",
      "id_number": "9505206800081",
      "institution": "UCT",
      "qualification": "BCom Accounting",
      "year_of_study": 3,
      "average_grade": 82.0
    }
  }'

Generic Select with Filters

curl -X POST "http://localhost:8000/api/v1/generic/select" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "applications",
    "columns": ["id", "first_name", "last_name", "email", "status"],
    "filters": {
      "status": "submitted",
      "year_of_study": 2
    },
    "limit": 50,
    "offset": 0
  }'

Bulk Insert Payments

curl -X POST "http://localhost:8000/api/v1/generic/bulk-insert" \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "payments",
    "records": [
      {
        "application_id": 1,
        "amount": 50000,
        "payment_type": "tuition",
        "payment_method": "eft",
        "bank_name": "FNB",
        "account_number": "62123456789",
        "account_holder": "John Doe"
      },
      {
        "application_id": 2,
        "amount": 5000,
        "payment_type": "allowance",
        "payment_method": "eft",
        "bank_name": "Standard Bank",
        "account_number": "12345678",
        "account_holder": "Jane Smith"
      }
    ]
  }'

🌐 Available Tables

applications - Bursary applications with applicant details
payments - Payment records with Sage Intacct integration
documents - Document metadata (files stored in Azure Blob)
audit_logs - Comprehensive audit trail for all changes

🔒 Response Codes

200 OK - Successful GET/PUT request
201 Created - Successful POST request (resource created)
204 No Content - Successful DELETE request
400 Bad Request - Invalid request data or parameters
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

🚀 Getting Started

Visit /api/docs for interactive API exploration
Use the examples above to test endpoints
Check /health to verify API status
Review /api/redoc for detailed documentation