Skip to content

API_ALIGNMENT.md

Latest commit

 

History

History
188 lines (145 loc) · 5.56 KB

API_ALIGNMENT.md

File metadata and controls

188 lines (145 loc) · 5.56 KB

API Alignment with Investec Production APIs

This document shows how the sandbox accurately mirrors the real Investec API structure, ensuring your development experience translates directly to production.

✅ Production Alignment Status

All components now accurately reflect the official Investec API specification:

Component Alignment Status Details
OAuth Flow ✅ Exact Match Client credentials with Basic Auth + x-api-key
API Endpoints ✅ Exact Match /za/pb/v1/* path structure
Response Format ✅ Exact Match Includes data, links, and meta properties
Authentication ✅ Exact Match Bearer tokens with API key headers
Error Handling ✅ Exact Match Standard HTTP status codes and error formats

🔄 OAuth Authentication Flow

Sandbox Implementation

POST http://localhost:3000/identity/v2/oauth2/token
Authorization: Basic {base64(client_id:client_secret)}
x-api-key: mock-api-key
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=accounts

Production Implementation

POST https://openapisandbox.investec.com/identity/v2/oauth2/token
Authorization: Basic {base64(your_client_id:your_client_secret)}
x-api-key: your-api-key
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=accounts

Migration: Simply change the base URL and credentials!

📡 API Endpoints Mapping

Sandbox → Production

Sandbox Production Status
http://localhost:3000/za/pb/v1/accounts https://openapisandbox.investec.com/za/pb/v1/accounts ✅ Identical
http://localhost:3000/za/pb/v1/accounts/{id}/balance https://openapisandbox.investec.com/za/pb/v1/accounts/{id}/balance ✅ Identical
http://localhost:3000/za/pb/v1/accounts/{id}/transactions https://openapisandbox.investec.com/za/pb/v1/accounts/{id}/transactions ✅ Identical

� Response Format Compliance

All responses follow the exact Investec API structure:

{
  "data": [
    {
      "accountId": "1234567890",
      "accountNumber": "62012345678", 
      "accountName": "Demo Current Account",
      "accountType": "current",
      "currency": "ZAR",
      "currentBalance": 15432.50,
      "availableBalance": 14932.50,
      "referenceName": "Demo Account",
      "productName": "Private Bank Account"
    }
  ],
  "links": {
    "self": "https://openapisandbox.investec.com/za/pb/v1/accounts"
  },
  "meta": {
    "totalPages": 1
  }
}

🔐 Security & Headers

Request Headers (Consistent)

{
  'Authorization': 'Bearer {access_token}',
  'x-api-key': '{your-api-key}',
  'Content-Type': 'application/json'
}

Error Responses (Consistent)

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid"
}

🚀 Migration Guide

From Sandbox to Production

  1. Update Base URLs:

    // Sandbox
const baseUrl = 'http://localhost:3000';

// Production Sandbox
const baseUrl = 'https://openapisandbox.investec.com';

// Production
const baseUrl = 'https://openapi.investec.com';

  2. Update Credentials:

    // Sandbox (mock)
const config = {
  client_id: 'mock-client',
  client_secret: 'mock-secret',
  api_key: 'mock-api-key'
};

// Production (real)
const config = {
  client_id: process.env.INVESTEC_CLIENT_ID,
  client_secret: process.env.INVESTEC_CLIENT_SECRET,
  api_key: process.env.INVESTEC_API_KEY
};

  3. Code Stays Identical:

    • Authentication flow remains the same
    • API endpoints use same paths
    • Response parsing logic unchanged
    • Error handling patterns identical

📊 Validation Results

Tested Scenarios ✅

  • OAuth token exchange - Exact same flow
  • Account listing - Identical response format
  • Transaction history - Same data structure
  • Balance queries - Matching field names
  • Error conditions - Consistent error codes

AI Prompts ✅

All 14 prompts in the prompt pack generate code that works with:

  • ✅ Local sandbox
  • ✅ Investec sandbox environment
  • ✅ Investec production (with credential updates)

🎯 Benefits for Developers

  1. Seamless Migration - Code written for sandbox works in production
  2. Realistic Testing - Experience matches live API behavior
  3. Confidence - Know your integration will work before going live
  4. AI Accuracy - Generated code follows real API patterns

📚 Official Documentation

This sandbox is built from official Investec specifications:

  • Swagger Files: Located in Official swagger Docs/
  • Developer Portal: developer.investec.com
  • API Reference: Current with latest Investec API versions

🔍 Verification

To verify alignment, compare sandbox responses with the official API:

# Test sandbox
curl -H "Authorization: Bearer {sandbox_token}" \
     -H "x-api-key: mock-api-key" \
     http://localhost:3000/za/pb/v1/accounts

# Test production sandbox  
curl -H "Authorization: Bearer {real_token}" \
     -H "x-api-key: your-api-key" \
     https://openapisandbox.investec.com/za/pb/v1/accounts

Response structures will be identical!

✨ Conclusion

This sandbox provides a production-accurate development environment that eliminates surprises when deploying to live Investec APIs. Your development experience directly translates to production success! 🚀