📌 Versioning & API Changes

IBISWorld’s APIs are designed to be predictable and stable. We use major versioning in the URL (e.g., /industry/v3/...). Within a major version, we ship additive, backward-compatible changes without forcing you to rewrite your integration. Breaking changes are reserved for a new major version (e.g., v4).

Current stable major: v3

Older versions: v2 Developer Documentation website. v2 is currently supported per our deprecation policy below.

Versioning Scheme

URL versioning: https://api.ibisworld.com/{product}/v{MAJOR}/...

Example: /industry/v3/fullreport

Minor/patch: We do not expose minor/patch numbers in the URL. Non-breaking improvements ship continuously within a major.

Change Types (What to Expect)

Non-Breaking (no action required)

We will roll these out inside the same major version:

Additive fields in responses (nullable by default)

New endpoints (e.g., new “helper” or “list” endpoints)

New enum values (we’ll document them ahead of time)

Relaxed validation that accepts more inputs

Performance improvements or bug fixes that don’t change behavior

Potentially Breaking (rare within a major)

These require advance notice and typically launch in a new major:

Remove/rename fields or endpoints

Tighten validation in ways that reject previously valid requests

Change response structure or error codes in incompatible ways

Repurpose enum values or change their meaning

Deprecation Policy

When we deprecate a resource or version, we follow this process:

Announcement in the Changelog with target dates
a. Changelog: All API changes (additive, deprecations, migrations)
b. Release notes: Product and data updates affecting behavior
c. Schema docs: Every new field is documented with type, nullability, and example
d. Email notices: For breaking or time-sensitive changes (to technical contacts on your account)

Deprecation window (minimum 6 months; complex changes may allow 9–12 months)

Sunset: traffic to the deprecated version may receive 410 Gone after the window

During the window we may return informative headers:

Deprecation: true
Sunset: Wed, 30 Apr 2026 00:00:00 GMT
Link: </industry/v4/fullreport>; rel="successor-version"

Backward-Compatibility Guidelines

We follow these practices to keep upgrades smooth:

New response properties are optional and nullable initially

Required fields are introduced in preview first

Enums: adding values is allowed; removing or repurposing values is considered breaking

Pagination, filtering, and sorting defaults remain stable within a major

Error shapes remain stable; new error codes may be additive

Migration Playbooks

When we introduce a new major, we include targeted guides:

v3 → v4 (example outline)

Field mapping table (old → new)

Enum additions and safe-defaults

Sample requests/responses

Checklist for SDKs and ETL jobs

Known pitfalls & test cases

FAQs

Q: Do I need to upgrade for every change?
A: No - only for breaking changes that ship in a new major.

Q: Will you ever change behavior without notice?
A: Security/abuse fixes may ship urgently; otherwise we post to the Changelog and, for breaking changes, send email to account contacts.

Q: How long do you support an old major?
A: We aim for 12 - 18 months minimum after a new major version, unless security or third-party constraints require faster sunset.

Contact & Support

Questions about a change? Contact your IBISWorld representative or email support.

Request an extension? Tell us your migration timeline; we’ll try to accommodate within reason.

Report a regression? Provide request IDs, timestamps, and sample payloads.

📌 Versioning & API Changes

Versioning Scheme#

Change Types (What to Expect)#

Non-Breaking (no action required)#

Potentially Breaking (rare within a major)#

Deprecation Policy#

Backward-Compatibility Guidelines#

Migration Playbooks#

FAQs#

Contact & Support#