Skip to main content
Version: 2.4

tSM Public API versioning & lifecycle

This page explains how tSM versions its Public REST APIs, what changes you can expect without breaking your integration, and how deprecations/removals are communicated.

tSM Public API is REST-based, aligned with TM Forum Open APIs, and published as a standard OpenAPI 3.0 (Swagger) specification.

1) Which API versions exist​

1.1 Major version in the URL (stable contract boundary)​

tSM uses major versioning in the base path:

  • .../api/v1/... (legacy / deprecated)
  • .../api/v2/... (current)

v1 is deprecated and is planned to be removed; consumers should migrate to v2.

Practical meaning: within a given major version (e.g., v2) tSM aims to keep your integration working across upgrades, as long as you follow the compatibility expectations in this document.

1.2 Where you see the exact contract that is deployed (OpenAPI “contract version”)​

Each tSM module exposes its OpenAPI spec via Swagger UI inside the tSM gateway, e.g.: .../tsm-gateway/<module>/swagger-ui/index.html (user management, ticketing, ordering, customer, etc.).

In Swagger/OpenAPI you will see an info.version value. In tSM this is treated as a contract/specification version (not a “different endpoint path”). The URL major version stays v2 unless a breaking change is introduced.

2) Compatibility guarantees within a major version (e.g., v2)​

2.1 What is considered backward compatible​

The following changes can happen within the same major version (/api/v2) and are intended to not break correctly implemented clients:

  • Adding new optional properties to responses
  • Adding new optional properties to requests (server continues to accept the request without them)
  • Adding new endpoints (new resources / operations)
  • Adding new enum values if your client can safely handle unknown values

2.2 What your client must do to stay compatible​

To benefit from the “non-breaking within v2” model, your integration must follow these rules:

  • Ignore unknown JSON properties in responses (forward-compatible deserialization).
  • Do not assume enums are closed unless explicitly documented; handle unknown values gracefully.
  • Do not rely on undocumented fields or undocumented side effects.

3) What is a breaking change (requires a new major version)​

A new major version (e.g., /api/v3) is required if a change can break existing clients, such as:

  • Removing or renaming an endpoint
  • Removing or renaming a field
  • Changing a field type/format in a way that changes JSON shape (e.g., string → object, integer → string)
  • Making an optional field required
  • Changing semantics in a way that can alter business meaning for existing requests

4) Deprecation & removal policy (how you will be notified)​

tSM uses a two-step lifecycle:

  1. Deprecated — still available and functional
  2. Removed — endpoint/behavior is no longer available (typically in a new major version)

4.1 How deprecation is communicated​

When an endpoint (or behavior) becomes deprecated, tSM will communicate it via:

  • OpenAPI/Swagger marking (where applicable) using the OpenAPI deprecated capability. (OpenAPI Initiative Publications)

  • HTTP response headers to make deprecation visible at runtime:

    • Deprecation header to signal that a resource is deprecated (or will be deprecated at a specific date). (IETF)
    • Sunset header to communicate the planned date when a deprecated resource is expected to become unavailable. (IETF)
    • A Link header may be used to point to migration guidance and alternatives (commonly used alongside these mechanisms). (IETF)

For consumers, the important part is: you should be able to detect deprecations both in the published spec and directly in HTTP responses.

4.2 What you should do when you see deprecation​

  • Stop onboarding new integrations to deprecated endpoints.
  • Plan migration to the documented replacement (usually within the same major version first; otherwise to the next major version).
  • Monitor the Sunset date if provided. (IETF)

5) Change categories (what “minor” and “patch” mean for you)​

Even though the URL major version is the primary API version selector (v2), tSM also uses an OpenAPI contract version (info.version) to help you track what changed between tSM releases.

5.1 Major-level changes (breaking change)​

Breaking changes require a new URL major version (/api/v3) and will be accompanied by deprecation/removal notices as described above.

Examples (contract version change):

  • 1.0.1 → 2.0.0
  • 2.3.4 → 3.0.0

5.2 Minor-level changes (compatible contract extension)​

You may see a new contract minor version when:

  • New optional properties are added to request/response models
  • New endpoints are added
  • Deprecation metadata is introduced (marking existing operations as deprecated)

Examples (contract version change):

  • 1.0.1 → 1.1.0
  • 1.2.0 → 1.3.0

5.3 Patch-level changes (no contract change)​

You may see a new contract patch version when:

  • Documentation, examples, descriptions, or clarifications are updated
  • Non-functional fixes that do not change the API contract are delivered

Examples (contract version change):

  • 1.0.1 → 1.0.2
  • 1.4.7 → 1.4.8

6) Where to find the authoritative API documentation​

The authoritative contract for each tSM module is published as OpenAPI/Swagger in the tSM gateway UI, for example:

https://<your-environment>/tsm-gateway/<module>/swagger-ui/index.html

This spec is the source of truth for:

  • endpoint paths and methods
  • request/response schemas
  • deprecated flags and migration notes (when applicable)

7) Quick checklist for robust integrations​

  • ✅ Use v2 endpoints (v1 is deprecated).
  • ✅ Generate client code from the OpenAPI spec where possible (or validate against it).
  • ✅ Ignore unknown response properties.
  • ✅ Monitor Deprecation / Sunset headers and act before deadlines. (IETF)
  • ✅ Treat OpenAPI as the contract; treat “contract version” (info.version) as the signal of compatible evolution inside a major.

If you want, paste me one of your current v2 Swagger URLs (e.g., ticketing or customer module) and I’ll tailor this page to include your exact base URLs, and add a short “Examples” section showing what deprecation headers look like in real HTTP responses.