API Versioning

What is API versioning?

API Versioning is the process of tracking and managing changes to an API over time. The main goal is to allow updates and improvements to be made without unexpectedly breaking the systems and applications that rely on the API.

This involves:
– Giving each update a unique tag or “version” (like v1, v2, or 2024-01-01).
– Making sure clients know which specific version they are using.
– Continuing to support older versions for a period, even after a new one is released.

Why versioning is important
APIs naturally change and evolve over time, for instance, data fields might be renamed, security methods might be updated, or an entire endpoint might be removed.

Without versioning, any change you make could instantly cause every existing integration relying on your API to fail. Versioning acts as a safety measure, ensuring stability for all your users.

When should you create a new API version?

You need to create a new version of your API whenever the changes you make will require developers to modify their existing code to keep their applications working.

Scenarios requiring a new version (Breaking changes)

Versioning is necessary in these typical situations:

– Removing or renaming: You remove an existing field, rename a parameter, or change the name of an entire endpoint.
– Changing the format: You change the basic structure of the data in the responses (e.g., changing a date field from a string to a number).
– Major overhaul: You introduce large new features or completely change how the API works, making the new behaviour incompatible with the older version.

When versioning may not be needed (Non-breaking changes)

You can usually avoid creating a new version if the change is fully backwards-compatible and won’t break existing apps:
– Adding new fields: You add a brand new, optional field to an existing response.
– Internal control: The API is used only internally within your company, and you control the code on both the sending and receiving sides.

API versioning strategies

Versioning is crucial for maintaining a stable API while allowing for continuous development and changes. Several schemes exist to identify and manage versions of an API.

Common versioning methods

These are the primary ways to distinguish between different API versions:

– URL or path versioning: This involves embedding the version number directly into the API endpoint (the path).

Example: /v1/resource or /api/2.0/users

– Query-parameter versioning: The client specifies the desired version by including it as a parameter in the query string of the URL.
Example: /resource?version=2

– Header versioning: The version is communicated via custom HTTP headers or standard ones.

Custom Header Example: X-API-Version: 2
Standard Header Example (less common): Using the Accept header.

– Content-negotiation (Media-type versioning): The client requests a specific media type (or MIME type) that includes the version information. This often uses the standard Accept header.
Example: Accept: application/vnd.example.v2+json

Strengths and weaknesses of each scheme

Each versioning scheme involves trade-offs regarding maintainability, RESTfulness, and client ease of use:

1. URL or path versioning

– Strength: It is the most simple, visible, and intuitive method, making the version clear to the developer just by looking at the URL.
– Weakness: It can lead to a proliferation of endpoints and requires maintaining many similar code paths (e.g., /v1/users, /v2/users), which can complicate long-term maintenance.

2. Header or media-type versioning

– Strength: It helps keep the URL clean and allows for greater flexibility as the resource’s URL itself does not change. Media-type versioning is often considered the most RESTful approach, utilizing the built-in HTTP content negotiation features.
– Weakness: It may be harder for clients or tooling (like a browser or simple HTTP client) to handle, as the version information is hidden within the request headers, making it less discoverable than a URL change.

3. Query-parameter versioning

– Strength: It is easy to implement quickly and provides a simple way for clients to request a specific version.
– Weakness: It is generally considered to stray from strict RESTful design principles, as a query parameter is usually intended for filtering or sorting, not for identifying the fundamental resource representation itself.

Best practices for API versioning

Following good habits when managing your API versions will minimise disruption for developers and keep your platform stable.

Consistency and communication

– Be consistent: Use your chosen versioning scheme (e.g., URL or headers) consistently across your entire API portfolio. This way, developers always know exactly what to look for and how to upgrade.
– Communicate clearly: Always tell your users what’s happening. You must document version changes, publish detailed migration guides showing how to switch, and announce deprecation and support timelines well in advance.
– Monitor usage: Track which versions are actually being used by clients. Knowing the usage statistics allows you to determine when you can safely retire an old version.

Managing change

– Maintain compatibility: Aim to maintain backward compatibility wherever you can. If a change doesn’t break existing code, existing integrations can keep working without being forced to update.
– Be strategic about versioning: Avoid versioning for trivial changes (like adding an optional field). Only create a new version when the change is breaking and will impact clients in a meaningful way.
– Plan retirement: Have a clear deprecation and retirement policy for older versions. Give developers fair notice, maintain support for the agreed-upon period, and only then safely retire the version when usage drops to zero.

The lifecycle of an API version

The lifecycle covers the complete journey of a specific API version, from the moment it is released until it is permanently turned off.

Key stages of the lifecycle

– Release: This is the point when a new version of your API (e.g., v3) is made available for developers and clients to start using.|
– Co-existence: During this crucial phase, the old version (v2) and the new version (v3) run side by side. This gives clients enough time to switch their code over without their service breaking.
– Deprecation: You formally mark the older version (v2) as deprecated. This means you inform all users that the version will be retired soon and strongly advise them to start the migration process immediately.
– Migration: This is the active stage where you guide clients to adopt the new version (v3), providing them with documentation, support, and tools to make the transition as smooth as possible.
– Retirement: The final stage. The older version (v2) is permanently removed or disabled. Any clients who are still using that retired version will instantly lose support and functionality.

 Sportmonks’ Versioning (from v2 to v3)

Sportmonks made a major shift from its original Football API (v2) to the new version 3 (v3) (or API 3.0). This was necessary to meet the growing demand for richer, more reliable, and real-time data that the older system couldn’t support.

The move to v3 ensures better reliability, higher data quality, wider coverage, and prepares clients for future innovations.

What’s new and different in v3

The v3 API has significant improvements over v2:

Data quality and structure

– Improved reliability: V3 uses an entirely new backend designed for better stability, faster live updates, and more accurate data checks.
– Cleaner data: V3 only returns actual statistical values. It no longer returns default zeros for missing data, which provides a cleaner and more accurate dataset.
– Stronger typing: The data structure includes clearer definitions for states and types.

New features and endpoints

– Richer coverage: New entities have been added, including transfers, referees, schedules, and coaches.
– Advanced data: V3 supports far more granular features, such as ball coordinates (semi-live), detailed player positions (e.g., left-back), offside events, coach and referee statistics, and pressure indices.
– Unified API: The main data and odds endpoints are now unified, supporting a potential multi-sport approach beyond just football.

Structural changes

– Base URL: The API address now includes the version prefix: https://api.sportmonks.com/v3/football/…
– Rate limits changed: In v2, limits were based per endpoint per hour. In v3, limits are based on per entity per hour (e.g., limits apply per fixture or per team request).
– Syntax: Filtering and sorting syntax has been updated (e.g., using filter[entity]=…).

Why migrating to v3 is essential

– Future innovation: All new features and enhancements will only appear in v3. Staying on v2 means missing out on crucial tools for your business.
– Performance: V3 offers improved data accuracy, expanded coverage, and more granular features that will directly improve your user experience and analytics.
– Retirement: While v2 will remain active until at least the end of 2025, relying on it indefinitely leaves your service vulnerable to the eventual shutdown (sunset).

Migration guidance: A structured approach

Follow these steps to successfully move your integration from v2 to v3:

1. Review and map the differences

– Use the Sportmonks documentation page detailing “Differences between API 2 and API 3“ to see where key changes occurred (renamed endpoints, model changes, filter syntax).
– Map every existing feature you use in v2 (e.g., getting team data via /v2/teams) to its new v3 path (e.g., /v3/football/teams).

2. Update your codebase

– Change the base URL from the v2 path to the v3 base URL.
– Adapt your code to the new filtering syntax, include parameters, and sorting options.
– Adjust the logic that handles the response structure, as some deprecated fields were removed, and data arrays may have changed slightly.
– Crucially, update your rate-limit handling and monitoring to accommodate the new entity-based quotas.

3. Test thoroughly

– Run parallel calls to both v2 and v3 for your most critical endpoints and compare the results side-by-side to identify any discrepancies.
– Pay attention to statistics: V3 only returns recorded values, so look out for differences where v2 may have returned a default zero.
– Ensure your application handles the new error schemas and pagination correctly.

4. Roll-out and retirement

– Decide whether to switch your entire service in one step or gradually migrate endpoints one by one.
– Once you are fully confident in your v3 integration, stop calling v2 endpoints and remove all v2-specific legacy code.
– Update all internal documentation and developer guides to point exclusively to v3.

Final considerations

– Data comparison: Because the v3 data model is cleaner, some metrics may behave differently than they did in v2. Treat comparisons cautiously during the transition phase.
– Cost/licensing: Check your subscription plan for any cost adjustments related to new advanced features (like advanced statistics) that are available in v3.
– Live data: Take full advantage of v3’s improved performance and filtering capabilities to optimise your real-time and high-frequency data usage.

Upgrade confidently with Sportmonks Football API v3

API versioning keeps your systems stable as new updates roll out, and the Sportmonks Football API v3 is built to give you more power, precision, and reliability than ever before. Version 3 introduces richer coverage, stronger data structures, and improved performance while maintaining stability for developers migrating from v2.

With v3, you get unified data endpoints, enhanced statistics, new entities like referees, coaches, and transfers, and cleaner data that removes defaults and improves accuracy. The new version also features a redesigned backend for faster updates, clearer filtering syntax, and improved rate-limit logic (now based on entities instead of endpoints).

Start your free trial today and explore Sportmonks Football API v3, your next step toward faster, cleaner, and smarter football data integration.