Skip to main content

Versioning

The API uses two complementary version signals:

  1. Path major version — /v1. Bumped only for breaking, structural changes to the whole API. It's part of the base URL: https://papi.trendev.in/v1.
  2. Dated behavior contract — the Version header. A required, dated string that pins the precise request/response behavior your integration was built against.
Version: 2026-06-01

The header must match YYYY-MM-DD. Set it to the date you integrated (or last tested) against, and leave it fixed. That way, behavior-affecting changes we ship after that date won't alter how your existing code sees the API — you opt into newer behavior by bumping the date deliberately, after reviewing the changelog.

Why both​

The path version changes rarely (a true v2 would be a parallel surface). Most evolution — a new field, a new default, a tightened validation — ships continuously without a /v2. The dated header lets us do that without breaking you: a request pinned to 2026-06-01 keeps seeing 2026-06-01 behavior.

What's considered backward-compatible​

These can change without a new path version, 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 dated contract (and, if structural, a new path version). We publish these in the changelog ahead of time.

  • Pin a specific Version date in your client config; don't compute "today's date."
  • Review the changelog before bumping it, then test against the new date in staging.
  • Keep /v1 in your base URL; you'll only ever change it for a deliberate major migration.