Migration Guide

Current Version

The SeloraX Platform API is currently at v1. All endpoints use the /api/apps/v1/ namespace.

https://api.selorax.io/api/apps/v1/orders
https://api.selorax.io/api/apps/v1/products

Versioning Policy

SeloraX uses URL-based versioning. The version number is part of the API path (/v1/, /v2/, etc.).

What counts as a breaking change

The following changes would trigger a new API version:

Removing an existing endpoint
Removing or renaming a response field
Changing a field's data type
Changing the authentication mechanism
Changing the error response format
Making a previously optional parameter required

What does NOT require a new version

These changes happen within the current version without breaking existing integrations:

Adding new endpoints
Adding new optional query parameters (e.g. new filters)
Adding new fields to response objects
Adding new error codes
Adding new webhook event topics
Increasing rate limits

Defensive coding

Write your code to handle unknown fields gracefully. When the API adds new fields to a response, your code should ignore them rather than breaking. Avoid strict schema validation on responses.

Deprecation Process

When a new API version is released, the previous version will follow this lifecycle:

Announcement — Published in the Changelog with at least 6 months notice
Parallel availability — Both versions run simultaneously. The old version returns a Sunset header indicating the deprecation date
Migration window — Documentation and tooling provided to help migrate
Sunset — The old version returns 410 Gone after the sunset date

Preparing for Future Versions

To minimize migration effort when v2 eventually ships:

1. Use the versioned namespace

Always include /v1/ in your API paths. Never hardcode unversioned paths.

// Correct
const url = "https://api.selorax.io/api/apps/v1/orders";
 
// Avoid — will break if routing changes
const url = "https://api.selorax.io/api/apps/orders";

2. Parse responses flexibly

Don't fail on unknown fields. Use the fields you need and ignore the rest.

# Good — tolerant of new fields
order_id = data["order_id"]
status = data["order_status"]
 
# Risky — fails if a new field appears with unexpected type
validated = OrderSchema(**data)  # strict Pydantic model

3. Handle errors by HTTP status

Check the HTTP status code first, then the code field. New error codes may be added at any time.

if (response.status === 401) {
  // Re-authenticate regardless of the specific error code
  await refreshToken();
}

4. Monitor the Changelog

Subscribe to the Changelog to stay informed about new features, filters, and any upcoming version changes.

API v1 is stable and production-ready. All endpoints documented in this portal are covered by the backwards-compatibility policy above. No breaking changes will be made to v1 without following the deprecation process.

Questions

If you have questions about API versioning or need help preparing for future migrations, contact the SeloraX developer support team at [email protected].