Skip to content
E1 Developer

Versioning

The External API uses URL-path versioning. The current version is v1:

/api/supplier/v1/companies/{companyId}/speci-finder/results

When a future version is released, the new version will live at a new path (e.g. /api/supplier/v2/...) and v1 will continue to serve existing traffic for the deprecation window described below.

What counts as a breaking change

The following changes are breaking and will only be made in a new major version:

  • Removing a field from a response.
  • Changing the type of an existing field (e.g. string to number).
  • Changing the semantics of an existing field.
  • Removing an endpoint or changing its path.
  • Adding a new required request parameter.
  • Tightening validation on an existing parameter in a way that rejects previously-accepted inputs.
  • Changing the error code for an existing failure mode.

The following changes are non-breaking and may be made in the current major version without notice:

  • Adding a new field to a response.
  • Adding a new optional request parameter.
  • Adding a new endpoint.
  • Adding a new error code for a new failure mode.
  • Relaxing validation on an existing parameter.
  • Bug fixes where the existing behaviour was clearly unintended.

Your integration should therefore tolerate unknown response fields and not rely on a fixed set of error codes — new ones can appear at any time.

Deprecation process

When a v1 endpoint is scheduled for removal:

  1. E1 announces the deprecation in the Changelog and notifies integrating partners via the support channel.
  2. A minimum 90-day notice period runs before removal.
  3. During the notice period v1 continues to work unchanged; a v2 (or replacement) is available for integrators to migrate to.
  4. At the end of the notice period the deprecated endpoint is removed and will return 404 Not Found.

Checking the current version

The version is part of the URL path — there is no separate version header. Each response is implicitly the current shape of the version you requested.

If you’re using code generated from the OpenAPI spec, regenerate on a regular cadence to pick up non-breaking additions.