Skip to main content

Versioning Principles

A consistent, closely managed, versioned API​

At Orgvue we aim to give our customers industry leading APIs and part of our effort focuses on integration experience. We want our customers to be able to manage changes to the integration contracts ahead of time. For this to be possible we provide definitions of what we deem breaking and non-breaking changes, and how our feature release and deprecation strategy will affect your integrations moving forward.

What are "previews"?​

All the new endpoints or request/ response payloads are first released as “previews”. They aren’t implemented or released in the latest version of API until they’ve been tried and tested by our users.

If you would like to be involved in this testing get in touch via our support team at support@orgvue.com

Here is what this means for you:

  • preview features are not released or implemented in the latest version of our API.
  • aspects of preview features are subject to change based on customer feedback.
  • please wait for the "stable" released version of the feature before you start integrating against it.

Please get in touch to discuss any new features and timelines for general availability.

We want to deliver an integration that meets your needs. One way to help us achieve it is through early feedback from our customers. All the previews are subject to change based on the feedback we get from you.

When will Orgvue release a new version of the API?​

New versions of the API will be released when new features dictate that we must introduce breaking changes. We will continue to support past versions of the API and provide detailed information on how to migrate your integration to the latest version.

What is the Orgvue definition of a breaking change?​

Here is a list of what we consider a breaking change:

JSON schema​

  • Removing a required attribute-value pair in the response payload.
  • Changing a required attribute-value pair to optional in the response payload.
  • Renaming a required attribute in the request or response payload.
  • Changing a value type in the request or response payload.

Headers​

  • Removing a response header.
  • Renaming a response header.
  • Changing a response header to optional.

Endpoint path​

  • Removing an endpoint path.
  • Renaming path parameters of an endpoint path.
  • Changing the order of the path parameters.

Endpoint query parameters​

  • Removing a query parameter if this impacts the schema of the response.
  • Renaming a query parameter.

What is the Orgvue definition of a non-breaking change?​

Here is a list of what we consider a non-breaking change:

JSON schema​

  • Adding a required attribute-value pair to a response schema.
  • Adding an optional attribute-value pair to a request or response schema.
  • Reordering the sequence of attribute-value pairs in a response.
  • Any increase in data range, length of field or addition to an enumerated type.
  • Changing the content of the message attribute of an error response.

Headers​

  • Changing the HTTP status code of an error.
  • Adding a new response header to an existing resource.
  • Adding an optional request header.

Endpoint path​

  • Adding a new endpoint path.

Endpoint query parameters​

  • Removing a query parameter where the schema of the response is not impacted.
  • Adding a query parameter to an existing endpoint.

Performance​

  • Significant changes in SLAs or latency such as "the API is now faster".

Where can I find the changelog?​

You can find detailed information around incremental changes in each of our released versions in our changelog page.