API Versioning

We are thrilled to announce a significant enhancement to our API services: versioning. As part of our commitment to continuous improvement and seamless user experiences, we have implemented a robust versioning strategy that ensures backward compatibility while allowing for innovation and growth.

What does this mean for you? With versioning, you can confidently integrate our APIs into your applications, knowing that any future changes will be communicated transparently. Whether you’re an existing user or exploring FMTC’s APIs for the first time, this upgrade path ensures stability and flexibility.

Major.Minor.Patch

FMTC is adopting a Major.Minor.Patch versioning system. Let’s break it down:

1. Major Version: Represents significant changes that may break backward compatibility. When you increment the major version (e.g., from 3 to 4), it signals substantial modifications or a new API design. Consumers need to adapt their code to the new version.

2. Minor Version: Indicates minor enhancements or additions without breaking existing functionality. For example, going from 4.0 to 4.1 introduces new features but maintains compatibility with 4.0.

3. Patch Version: Reserved for bug fixes, security updates, or other non-disruptive changes. Incrementing the patch version (e.g., 3.0.0 to 3.0.1) ensures that existing integrations remain stable.

By adhering to Major.Minor.Patch versioning, FMTC is striving for a balance between innovation and stability, fostering a reliable API ecosystem.

New API URL Structure

https://www.s3.fmtc.co/api/{VERSION}/{ENDPOINT_NAME}?api_token=TOKEN

Specifying a Version

You can request a version at three levels of precision:

1. Major: Pass only the major version to always receive the latest release on that major version. For example, if the newest 4.x release is 4.2.0, requesting 4 returns 4.2.0.

   1. https://www.s3.fmtc.co/api/4/deals?api_token=TOKEN
      

2. Major.Minor: Pass the major and minor version to always receive the latest patch for that major.minor. For example, if 4.1.2 is the newest patch of 4.1, requesting 4.1 returns 4.1.2.

   1. https://www.s3.fmtc.co/api/4.1/deals?api_token=TOKEN
      

3. Major.Minor.Patch: Pass the full version to lock to exactly that release. For example, requesting 4.0.0 always returns 4.0.0, even after newer versions ship.

   1. https://www.s3.fmtc.co/api/4.0.0/deals?api_token=TOKEN
      

Which Version Is Best For You?

By introducing API versioning, FMTC is giving you the choice on how you receive your information. Here are the pros and cons for each different way to send the API version.

1. Major

   1. Pros: Ability to always be up to date with the latest FMTC version, including new features and bug fixes

   2. Cons: Risk of issues when a new API endpoint has been released

2. Major.Minor

   1. Pros: Keep up to date with bug fixes

   2. Cons: No new features

3. Major.Minor.Patch

   1. Pros: Reliability that once integrated your API endpoint will act exactly the same regardless of FMTC updates

   2. Cons: No bug fixes or new features

FMTC Recommendation

We recommend the Major.Minor approach (e.g., /api/4.1/deals). This lets you automatically receive bug fixes and security patches while protecting you from unexpected breaking changes introduced in new minor or major releases.

Previous Endpoint

The now deprecated endpoint is using the following structure:

https://www.s3.fmtc.co/api/v3/deals?api_token=TOKEN&additional_parameters...

We recommend migrating to the explicit numeric version format (/api/{VERSION}/{ENDPOINT}) when convenient.