Skip to main content

Versioning

The API version is a single major version, v1, surfaced in two places that always agree:

  1. Path — /v1. Part of the base URL: https://papi.trendev.in/v1.
  2. Version header. A required string carrying the same major version.
Version: v1

The header must match v<number> (e.g. v1). In the API reference, the Version field is a dropdown of the published versions with the latest selected by default, so you send the current version without having to remember it. If the header is missing or unrecognized, the gateway falls back to the latest published version.

Why a header too​

Keeping the version in a header (not only the path) lets tooling — the API reference "Try It" panel, SDKs, and gateways — surface and pin it explicitly, and lets us route on it if a future v2 ever ships as a parallel surface.

What's considered backward-compatible​

These can change within v1, and won't break a correctly written client:

  • Adding a new endpoint, resource, or optional request field.
  • Adding a new field to a response object.
  • Adding a new enum value, error type, or optional response header.
  • Relaxing a validation rule.

Write clients defensively to absorb these:

  • Ignore unknown fields rather than failing on them.
  • Don't hard-code enum exhaustiveness — handle an unrecognized value gracefully.
  • Branch on status / error type, not on human-readable strings.

What requires a new version​

Removing or renaming a field, changing a type, making an optional field required, or changing a default in a behavior-affecting way are breaking. These are gated behind a new major version (v2), published as a parallel surface with its own /v2 path and Version: v2. We announce these in the changelog ahead of time.

  • Send Version: v1 explicitly in your client config.
  • Keep /v1 in your base URL; you'll only change it for a deliberate major migration to v2.
  • Review the changelog before adopting a new major version, then test it in staging.