Skip to main content

Versioning & deprecation

The Evinor API is versioned in the URL path. The current version is v1, and every endpoint lives under /v1 (for example, GET /v1/sensors).

Additive-only within a version​

Within /v1, changes are additive and backward-compatible. That means we may, without a new version:

  • add new endpoints;
  • add new optional request parameters (existing requests keep working unchanged);
  • add new fields to response bodies.

Within /v1 we will not:

  • remove or rename an existing response field;
  • change the type or meaning of an existing field;
  • make a previously optional request parameter required;
  • remove an endpoint.

A change that would break any of those guarantees ships under a new version path (for example, a future /v2), never as an in-place change to /v1.

Build a tolerant client​

Because new fields can appear at any time, write your integration to be forward-compatible:

  • Ignore unknown fields rather than rejecting a response that contains them.
  • Don't depend on field ordering in JSON objects.
  • Branch on documented type URIs and status codes for errors, not on human-readable text (see Errors).

Following these rules means additive changes never break your integration.

Deprecation policy​

When we eventually deprecate part of /v1 in favor of a newer version, we commit to:

  • a minimum 12-month window between announcing a deprecation and removing the deprecated behavior;
  • advance notice, so you have time to migrate.

Once deprecation signaling is in place, deprecated endpoints will advertise it with standard HTTP response headers:

  • Deprecation — indicates the endpoint is deprecated.
  • Sunset — the date after which the endpoint may stop working.
note

These deprecation headers describe our forward-looking policy. The current /v1 API is not deprecating anything and does not emit Deprecation or Sunset headers today — they will appear only if and when a deprecation begins.

Changelog​

Notable additions and any deprecation announcements are published here on the Evinor developer portal. Check back before relying on newly added fields, and watch for deprecation notices if you depend on behavior slated to change.