Settings & Metadata

Access API version information and system metadata. This section covers retrieving version details and system information.

Overview

The Settings endpoints provide access to system metadata and version information. This is useful for:

Version checking - Verify API version compatibility
System monitoring - Check API status and version
Integration validation - Ensure your integration uses the correct API version

API Endpoints

Get API Version

Retrieve current API version information.

GET https://api.farpay.io/v2/settings/metadata/version

Response Example:

{
  "Version": "v2.1.0",
  "Created": "2024-01-15T10:30:00Z"
}

Version Properties

Property	Type	Description
`Version`	string	Current API version (read-only)
`Created`	string	Version creation date (read-only)

Version Information

Current Version: v2.1.0

The current stable version of the FarPay API provides:

Enhanced security - Improved authentication and authorization
Better performance - Optimized response times
Extended features - Additional endpoints and capabilities
Improved error handling - More detailed error responses

Version History

Version	Release Date	Key Features
v2.1.0	January 2024	Enhanced payment filtering, improved error messages
v2.0.0	December 2023	Major API overhaul, new authentication method
v1.x	Legacy	Deprecated, discontinued

Version Checking

Check API Version

// Verify API version before making requests
async function checkApiVersion() {
  try {
    const response = await fetch('https://api.farpay.io/v2/settings/metadata/version', {
      headers: {
        'X-API-KEY': 'your-api-key',
        'Accept': 'application/json'
      }
    });
    
    const versionInfo = await response.json();
    console.log(`API Version: ${versionInfo.Version}`);
    console.log(`Created: ${versionInfo.Created}`);
    
    // Check if version is supported
    if (versionInfo.Version.startsWith('v2')) {
      console.log('API version is supported');
    } else {
      console.warn('API version may not be supported');
    }
  } catch (error) {
    console.error('Failed to check API version:', error);
  }
}

Version Compatibility

Your Integration	API Version	Status
v2.x	v2.1.0	✅ Compatible
v2.x	v2.0.0	✅ Compatible
v1.x	v2.x	❌ Incompatible
v2.x	v1.x	❌ Incompatible

System Monitoring

Health Check

Use the version endpoint as a health check:

async function healthCheck() {
  try {
    const startTime = Date.now();
    const response = await fetch('https://api.farpay.io/v2/settings/metadata/version', {
      headers: {
        'X-API-KEY': 'your-api-key',
        'Accept': 'application/json'
      }
    });
    
    const responseTime = Date.now() - startTime;
    
    if (response.ok) {
      console.log(`API is healthy - Response time: ${responseTime}ms`);
      return true;
    } else {
      console.error(`API health check failed: ${response.status}`);
      return false;
    }
  } catch (error) {
    console.error('API health check error:', error);
    return false;
  }
}

Scheduled Monitoring

// Check API health every 5 minutes
setInterval(async () => {
  const isHealthy = await healthCheck();
  if (!isHealthy) {
    // Send alert or notification
    console.warn('API health check failed');
  }
}, 5 * 60 * 1000);

Error Handling

Common Error Responses

Status Code	Description
`200`	Success - Version information retrieved
`401`	Unauthorized - Invalid API key
`500`	Internal server error

Error Example

{
  "error": "Internal server error",
  "statusCode": 500
}

Best Practices

Check version on startup - Verify API compatibility when your application starts
Monitor regularly - Use the endpoint for health monitoring
Handle errors gracefully - Implement proper error handling for version checks
Log version information - Keep track of API versions for debugging
Plan for updates - Monitor for new API versions and plan migrations

Integration Examples

Node.js Integration

const axios = require('axios');

class FarPayAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.farpay.io/v2';
  }
  
  async getVersion() {
    try {
      const response = await axios.get(`${this.baseURL}/settings/metadata/version`, {
        headers: {
          'X-API-KEY': this.apiKey,
          'Accept': 'application/json'
        }
      });
      return response.data;
    } catch (error) {
      throw new Error(`Failed to get API version: ${error.message}`);
    }
  }
  
  async healthCheck() {
    try {
      await this.getVersion();
      return true;
    } catch (error) {
      return false;
    }
  }
}

// Usage
const farpay = new FarPayAPI('your-api-key');
const version = await farpay.getVersion();
console.log(`FarPay API Version: ${version.Version}`);

Python Integration

import requests
import time

class FarPayAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.farpay.io/v2'
    
    def get_version(self):
        try:
            response = requests.get(
                f'{self.base_url}/settings/metadata/version',
                headers={
                    'X-API-KEY': self.api_key,
                    'Accept': 'application/json'
                }
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise Exception(f'Failed to get API version: {str(e)}')
    
    def health_check(self):
        try:
            self.get_version()
            return True
        except Exception:
            return False

# Usage
farpay = FarPayAPI('your-api-key')
version_info = farpay.get_version()
print(f"FarPay API Version: {version_info['Version']}")

Related Endpoints

Authentication - API setup and authentication
Release Notes - Detailed version history and changes
Examples - Complete integration examples