Skip to main content

Client Versioning (Semantic Version Header)

Scope note: this version header contract applies to external Link Org API requests (proto/org.proto). It does not define a SIL-specific version header contract.

This API uses semantic versioning via a request header to enable backward-compatible evolution without changing service or method names.

The API itself is versioned in the Git repository, and the client version header is used to safely negotiate behavior within a given API version.

Overview​

Clients may optionally send their semantic version with each request using gRPC metadata:

link-semver: <semver>

Example:

link-semver: v1.4.2+7

If the header is omitted, the server assumes an unknown / legacy client and will default to the safest behavior.

Semantic Version Format​

The value of link-semver must follow semantic versioning:

vMAJOR.MINOR.PATCH+BUILD
  • MAJOR — breaking changes
  • MINOR — backward-compatible feature additions
  • PATCH — backward-compatible bug fixes
  • BUILD — build or revision number (used for fine-grained comparisons)

Examples of valid versions:

  • v1.0.0
  • v1.2.3
  • v2.4.1+5

The leading v is required. Invalid or malformed versions, including ones without the v, cause the server to ignore the header.

How the Server Uses This Version​

The server may conditionally enable behavior based on the minimum client version required for a feature.

Conceptually:

“Is the client running at least version X.Y.Z(+B)?”

Version comparison is performed in the following order:

  1. Major
  2. Minor
  3. Patch
  4. Build

A client is considered compatible if its version is greater than or equal to the required version.

Backward Compatibility Guarantees​

  • Minor, patch, and build increments are always backward-compatible
  • Breaking changes only occur across major versions

This means:

  • Upgrading your client’s minor or patch version should never break existing integrations
  • New features may be conditionally enabled for newer clients
  • Older clients will continue to receive stable, compatible responses

Multiple Headers​

Clients must not send more than one link-semver value per request.

❌ link-semver: v1.2.0
❌ link-semver: v1.3.0

If multiple versions are sent, the request may be rejected or treated as invalid.

  • Always send link-semver once your client is versioned

  • Treat unknown enum values (for example new AuditType values) as forward-compatible data; ignore/drop values you do not support

  • Treat ReceivedAudit payload variants as forward-compatible data; new payload types may appear over time

  • Increment:

    • PATCH for bug fixes
    • MINOR for backward-compatible features
    • MAJOR only when explicitly coordinated with the server

  • Treat omission of the header as a legacy compatibility mode

Current Implementation Notes​

The current public Link Org API has these important characteristics:

  • Aliro support was added to the public Org API, including device configuration operations and Aliro credential assignment flows
  • Aliro reader public keys are discovered through device summaries
  • Audit stream payloads evolve over time, so clients should tolerate new ReceivedAudit payload variants and unknown enum values
  • Credential profiles are supported through the current Org API for generic DESFire configuration

When writing a client, prefer capability-based handling over assuming a fixed payload set forever.

Summary​

  • The API is versioned in the Git repository
  • Client behavior is negotiated via the link-semver request header
  • Versions follow strict semantic versioning
  • The server enables features based on minimum client version
  • This approach allows safe, incremental evolution without endpoint churn