Skip to main content

​
Overview

The Moflay API uses URL-based versioning to ensure backward compatibility and provide a clear upgrade path for developers. All API endpoints are prefixed with a version identifier (e.g., /v1/) to maintain stability as the API evolves.

​
Current Version

API Version: v1
Base URL: https://api.moflay.com/v1/

​
Versioning Strategy

​
URL-Based Versioning

All API endpoints include the version in the URL path: 
https://api.moflay.com/v1/customers
https://api.moflay.com/v1/transactions
https://api.moflay.com/v1/express

​
Semantic Versioning

The API follows semantic versioning principles:
  • Major versions (v1, v2, etc.) - Breaking changes that require code updates
  • Minor versions - New features and enhancements (backward compatible)
  • Patch versions - Bug fixes and improvements (backward compatible)

​
Backward Compatibility

​
Within Major Versions

  • Guaranteed compatibility - No breaking changes within the same major version
  • New features - Additional endpoints, parameters, and response fields
  • Enhanced responses - New optional fields added to existing responses
  • Deprecation warnings - Advance notice before removing features

​
Breaking Changes

Breaking changes only occur in new major versions and may include:
  • Removing endpoints or parameters
  • Changing response structure
  • Modifying authentication requirements
  • Changing data types or validation rules

​
API Evolution

​
Adding New Features

New features are added to the current version without breaking existing functionality: 
// New optional field added to existing response
{
  "id": "cus_ABC123",
  "name": "John Doe",
  "email": "john@example.com",
  "phoneNumber": "254712345678",
  "createdAt": "2024-12-01T10:00:00.000Z",
  "lastActiveAt": "2024-12-19T16:45:00.000Z", // New field
  "preferredPaymentMethod": "m-pesa" // New field
}

​
Deprecation Process

When features are deprecated:
  1. Deprecation notice - Added to API responses and documentation
  2. Grace period - Feature remains functional for a specified period
  3. Removal - Feature removed in next major version
Example deprecation warning in response headers: 
X-API-Deprecation: "The 'old_field' parameter will be removed in v2.0.0. Use 'new_field' instead."

​
Version Headers

​
API Version Header

You can specify the API version using the X-API-Version header: 
curl -H "Authorization: Bearer mf_test_1234567890" \
     -H "X-API-Version: v1" \
     "https://api.moflay.com/v1/customers"

​
Migration Between Versions

​
Planning Your Migration

  1. Review changelog - Check what’s changed in the new version
  2. Test in staging - Use the new version in a test environment
  3. Update gradually - Migrate endpoints one at a time
  4. Monitor usage - Watch for any issues during migration

​
Migration Timeline

  • Announcement - New version announced 90 days before release
  • Beta period - Beta version available for testing
  • Release - New version becomes stable
  • Deprecation - Old version marked as deprecated
  • Sunset - Old version retired (6+ months after deprecation)

​
Best Practices

​
1. Always Specify Version

Always include the version in your API calls: 
# Good - Explicit version
curl "https://api.moflay.com/v1/customers"

# Avoid - Implicit version (may break)
curl "https://api.moflay.com/customers"

​
2. Plan for Updates

  • Subscribe to updates - Follow our changelog and announcements
  • Test regularly - Test your integration with new versions
  • Update gradually - Don’t wait until the last minute to migrate

​
Version History

​
v1.0.0 (Current)

Released: December 2024
Status: Stable
Features:
  • Customer management
  • Transaction processing
  • Express payments
  • Webhook support
  • Cursor-based pagination
  • Comprehensive filtering and sorting

​
Upcoming Versions

v2.0.0 (Planned)
  • Enhanced webhook system
  • Advanced analytics endpoints
  • Improved error handling
  • Additional payment methods

​
Support and Resources

​
Getting Help

  • Documentation - Comprehensive guides and examples
  • API Reference - Interactive endpoint documentation
  • Support - Contact support@moflay.com
  • Status Page - Check API status at status.moflay.com

​
Staying Updated

  • Changelog - Follow our changelog for updates
  • Newsletter - Subscribe to our developer newsletter
  • GitHub - Watch our repositories for updates
  • Twitter - Follow @moflay for announcements

​
Troubleshooting

​
Version Not Found

If you receive a “version not found” error:
  1. Check URL format - Ensure you’re using the correct version path
  2. Verify version exists - Check if the version is still supported
  3. Update client - Make sure you’re using a supported version

​
Deprecated Features

If you see deprecation warnings:
  1. Read the warning - Understand what’s changing
  2. Plan migration - Update your code to use new features
  3. Test changes - Verify everything works with the new approach
  4. Update gradually - Don’t rush the migration

​
Breaking Changes

If you encounter breaking changes:
  1. Check changelog - Review what changed in the new version
  2. Update code - Modify your integration accordingly
  3. Test thoroughly - Ensure all functionality works
  4. Monitor metrics - Watch for any issues in production
⌘I