Skip to main content

Versioning & migration

/api/v1 is the stable contract​

Use only the /api/v1 paths. They are the versioned, stable contract with clean, documented data shapes.

Unversioned paths are deprecated​

The earlier unversioned paths (/api/workspaces/… without /v1) still work unchanged, but are marked deprecated. They send the corresponding HTTP headers:

Deprecation: true
Link: </api/v1/workspaces/{workspaceId}/glasses>; rel="successor-version"

In the API Reference these operations are marked deprecated and link to their /api/v1 successor.

Migration​

  1. Replace the path prefix /api/… with /api/v1/….
  2. Note the cleaner v1 shapes: hasImage/imageUrl instead of embedded images, camelCase, lean references (glass: { id, name }), aggregates (averageRating, ratingCount).
  3. GET single-resource fetches now return 404 when not found (instead of 200 with null).

Future versions​

Breaking changes appear as a new version (/api/v2, …). /api/v1 remains available and is deprecated in turn before it eventually gets an optional sunset date (Sunset header).