11 Versioning

All APIs are exposed by the Oracle Hospitality Integration Platform version at the URI level. This means that the URI includes /v0, /v1, /v2, and so on.

The current versioning strategy avoids versions beyond v1 by introducing non-breaking changes and only introducing major changes when necessary.

In the future, versions beyond v1 might be considered.

As any piece of software, our APIs change and mature over time. Inevitably, a given API operation is more mature in later versions of the product, regardless of the version given to the operation. For example, if an API operation has a bug fixed in vLatest, then the API call might hit that bug when calling an older version of the product. Each API producing product issues its own Release Readiness Guide (for example, the OPERA Cloud Release Readiness Guide) that outlines the API bugs fixed in each version. If the API operation being called is affected by a bug in an older version of OPERA Cloud, then the hotelier should upgrade to receive the bug fix.

What is a non-breaking change?

Oracle Hospitality considers the following changes to be backwards-compatible:

  • Adding new API operations.

  • Adding new optional request parameters to existing API operations.

  • Adding new properties to existing API responses.

  • Adding new response headers.

  • Changing the order of properties in existing API responses.

  • Updating descriptions of API operations or properties.

  • Adding or changing examples.

  • Increasing the length of a string parameter.

  • Changing from a more restrictive to a less restrictive numeric datatype for example, "number" to "integer" or "float" to "number").

  • Deprecating an API operation.

  • Adding items to or removing items from an ENUM.

    • If using a strongly typed language, such as Java, ensure that code is resilient to changes in ENUMs. For example, by specifying the ‘enumUnknownDefaultCase’ parameter in the Java OpenAPI Generator or the ‘READ_UNKNOWN_ENUM_VALUES_AS_NULL’ parameter in Jackson in Java.

  • Adding new events.

    • Ensure your Streaming WebSocket client and your REST API event parsing code gracefully handles unfamiliar events.

What is a major change?

We consider major changes those that can break existing API integrations. For example:

  • Removing an entire API operation.

  • Removing or renaming a request parameter.

  • Removing or renaming a response parameter.

  • Adding a new required request parameter.

  • Making a previously optional parameter required.

  • Changing the datatype of a parameter or response field (for example, from integer to string).

  • Adding a new validation rule to an existing request parameter.

  • Changing authentication or authorization requirements.

  • Enforcing new or lower limits on request parameters.

  • Changing how resources are accessed. For example, requiring that salesManagerGoals are accessed via salesManagers.

  • Request body size changes. For example, allowing a whole profile (including children) in the request body to allowing only summary profile data in the request body.

  • Adding validation to allow fewer items in an array in the request body.

  • Response body size changes. For example, returning a subset of a profile where previously the API returned the full profile or vice versa. Or changing the number of items that are returned when no pagination parameters are specified.

  • Changing response error codes.

How can I find out about major changes?

Refer to the following Customer Support article: Oracle Hospitality Integration Platform Upcoming Major Changes. To be notified when the Upcoming Major Changes log is updated, click the Subscribe button on that page.

Subscribe to the Oracle Hospitality Github repository to receive updates on the major changes in new releases.

Regularly check the Upcoming Major Changes section of this user guide.

How do I know when new APIs are released?

The Oracle Hospitality Integration Platform Patch Release Notes list all new and deprecated APIs. To be notified when a new patch release note is issued, click the Subscribe button on that page.

Subscribe to the Oracle Hospitality Github repository to receive updates on the major changes for new releases.

Further, each Oracle Hospitality product publishes a Release Readiness Guide that also lists changes to APIs and new APIs. For example, the OPERA Cloud 24.1 Release Readiness Guide lists the new API features included in OPERA Cloud 24.1.

Deprecation Schedules

Oracle Hospitality APIs are deprecated at the level of the operation and no lower.

A major change announcement is issued as soon as possible once an API operation will be deprecated. This major change announcement includes details of the sunset date.

For example, the OPERA Cloud Property Early Adopter APIs (/v0) were deprecated September 2023.

The first diagram shows an old API operation being available. A new API operation is later created. At some point, the old API operation is deprecated and a major change notification is issued. Eventually, the old API operation is sunsetted and no longer available, and the new API operation continues to be available. The second diagram shows the OPERA Cloud Property v0 APIs being available. Later, the OPERA Cloud Property v1 APIs became available. In September 2023, the OPERA Cloud Property v0 APIs were deprecated and a major change notification announced that OPERA Cloud Property v0 APIs would be sunsetted in December 2024 after which they would not be available. The OPERA Cloud Property v1 APIs continue to be available.

The Oracle Hospitality Integration Platform exposes APIs from multiple SaaS products, and each SaaS product is versioned (for example, OPERA Cloud 23.5). This SaaS product version number can be read in the API specifications file.

When developing and listing integrations on the marketplace, it is important to be clear about which version of the SaaS product was used during the development.

Integration partners have access to the sandbox where they can test changes they made to adapt to major changes ahead of when those changes are introduced in a later version of the SaaS product. Customers also have UAT environments which are upgraded ahead of production environments. However, the time between a customer UAT environment being upgraded to a given version and the same customer's PROD environment being upgraded is short, so customers must start preparations as soon as the major change announcement is received and quickly test it in their UAT environment.

The diagram shows changes in the SaaS product version in different environments across four different time windows. In the first time window, the partner sandbox is on SaaS product version 23.5. In the second time window, the partner sandbox is on SaaS product version 24.1, and a customer User Acceptance Testing environment is still on SaaS product version 21.5.  During this time window, the major change notification is published allowing customers and integration partners to prepare for the breaking change. In the third time window, the partner sandbox is on SaaS product version 24.2, which contains a major change. Meanwhile, the customer User Acceptance Testing environment is on SaaS product version 24.1, and the customer production environment is still on SaaS product version 21.5. In this time window, partners can test their changes as the partner sandbox is on SaaS product version 24.2, which is the one with the major change. In the fourth time window, the customer User Acceptance Testing environment is on SaaS product version 24.2, which contains a major change, while the customer production environment is still on SaaS product version 24.1. Customers must use this short time window to test their changes in the customer User Acceptance Testing environment. In the fifth time window, the customer production environment is on SaaS product version 24.2, which contains a major change.

How to adapt to deprecation notices

  1. Read the major change announcement and determine whether the change affects any APIs you current use or intend to use.

  2. If you are affected by a major change, take immediate action in the following environments:

    1. For integration partners, a sandbox environment.

    2. For customers, a UAT environment.

  3. Verify that after taking action, the integration works as needed.

  4. Wait for the upgrade to the affected version of the SaaS environment.

    1. For integration partners, test this in the sandbox environment

    2. For customers, test this in a UAT environment. Note that production environments are quickly updated after UAT environments, so prioritize this testing as soon as the UAT environment is upgraded.

  5. Deploy the changes to production environments before they are updated to the affected version of the SaaS product.

Example of adapting to a deprecation notice:

In April 2024, a major change announcement was issued about API limits. Do the following in response:

  1. Read the major change announcement for April 2024 and determine whether your integration is affected. Continue with the below steps if it was affected:

  2. Immediately make the changes as outlined in the Call to Action, and test these changes in a sandbox or a UAT environment.

  3. Test the whole integration still works even with the changes.

  4. Wait for the upgrade to OPERA Cloud 24.4 in the following environments:

    1. For integration partners, a sandbox environment. Be sure to test these changes.

    2. For customers, a UAT environment. Be sure to test these changes.

  5. Deploy the changed integration and make it live before OPERA Cloud 24.5 is deployed to any production environment.