Property APIs

Table 18-2 Property APIs

Best Practice	What to avoid and why
For extracting bulk data such as folios and profiles, use Oracle Reporting and Analytics.	Using the REST APIs to extract bulk data can cause operational impact on the hotel.
For shopping availability across many different properties use the Oracle Hospitality Distribution Shop API, which is specially designed for this purpose and returns data from a live cache. For example, I want to create a reservation for a guest at Hotel1 and subsequently book another reservation for the same guest at Hotel2. The Shop API provides functionality that allows you to check availability across multiple properties.	Using the Property REST API to get availability at each resort, which is slower and more costly.
After obtaining an oAuth token, check the oAuth token's expiry time in the "exp" attribute of the JWT (oAuth token) and then request a new oAuth token two minutes before the "exp." Code that makes API calls can then use the cached token, ensuring it remains consistently valid.	Requesting a new oAuth token with every API call. Requesting an oAuth token is billable for integration partners. Furthermore, requesting oAuth tokens too frequently can create an operational impact on identity servers.
When creating or modifying reservations, always use codes (such as rate, room type, source codes, market codes, address types, membership types) that are valid for the resort. Use the List of Values Management and Enterprise Configuration APIs to identify the specific configuration of the resort being accessed. An example is postReservation. When creating a new reservation, there are codes required as part of the request body. Prior to posting the reservation, ensure you have called the List Of Values, such as getSourceCode, getMarketCodes, getGuaranteeCodes, getMembershipTypes, and so on. The postman workflow samples provide an integrator with a recommended sequence of operations to execute before posting a new reservation and should be reviewed before starting to build your integration.	Send any values in these codes or use values that are relevant for one resort, but not for the resort being requested. OPERA Cloud is highly configurable and most of our OPERA Cloud customers leverage this to create the unique experiences offered by their resort. This means that many configuration items will differ from one resort to another. Failure to use codes valid for the property will result in reservations being created in OPERA Cloud with invalid codes. As soon as a user views the reservation, the user must update the reservation with valid codes.
Call Oracle Hospitality APIs only from back end systems. If Oracle Hospitality APIs are needed as part of a browser or mobile app-based experience, implement a "Backend for Frontend (BFF)" pattern, which creates an abstraction layer consuming OHIP APIs and provides Experience APIs that are better suited to be called from mobile apps or web browsers.	Calling Oracle Hospitality APIs directly from a web browser or mobile app. The Oracle Hospitality APIs are certified only to be called from back-end systems. This is partly a security measure and partly due to the APIs not being optimized for mobile data limitations.
Implement the "Tolerant Reader" pattern so that consuming code looks only at the fields needed by the implementation.	Tying integrations too tightly to API specifications. As business APIs, the Oracle Hospitality APIs contain a wealth of data. However, a given integration may need only some of that data. While we always support backwards compatibility for v1 APIs, it is our goal to also support this for v0 APIs. However, changes can occur, and the Tolerant Reader pattern can reduce the impact radius of these API changes.
When writing Experience APIs for consumption by mobile apps or web browsers, use "API Composition" to gather all the required information from multiple Oracle Hospitality APIs together with the "Backends for Frontends" pattern to orchestrate multiple OHIP API calls but expose them as a single Experience API.	Write Experience APIs for consumption by mobile apps or web browsers that are 1:1 copies of the Oracle Hospitality APIs. The Oracle Hospitality APIs are business APIs, which are likely to contain more data than a mobile app or web browser needs. Similarly, a specific Oracle Hospitality API might not provide sufficient data to meet the needs of a mobile app or web browser.
Use Business Events to see when a given resource has changed. Assuming Business Events are configured, every change that occurs within our Hospitality applications triggers a Business Event. For details on consuming these events, see Business Events. For example, my integration requires housekeeping information to be kept in sync with OPERA Cloud. Rather than GETting the data using the Housekeeping APIs, configure the business events for the housekeeping module. This will ensure events are generated and sent to the external system each time a resource is changed directly in OPERA Cloud. As soon as someone changes a room to Out of Order in OPERA, a business event is generated for the external system.	Continuously calling GET on a resource or a collection of resources and parsing the data to see if anything has changed.
Place consuming architecture as close to the OHIP gateway as possible to minimize network latency. As a benchmark, fetching an OAuth token should take no longer than 100ms.  For ultimate speed and low latency, consider implementing your BFF in the same region as the OHIP API Gateway and housing the OPERA Cloud instance(s) within the Oracle Cloud Infrastructure (OCI). Not only does this reduce latency, but it also increases security because the API traffic remains inside of Oracle Cloud.	Place consuming architecture in one location and consume events from all regions. Network latency can have a negative impact on users of the application connecting to OHIP. A high latency connection to the Streaming API can result in a massive backlog of events that can never be consumed.
Use the circuit breaker pattern to retry the same API call when receiving an error. This is particularly important when orchestrating multiple OHIP API calls. When the resource is very large, the retry logic must be the following: Retry the same call 30 minutes later. If the retry also times out, move the call to an error hospital and create a technical Service Request with all the details by following the process described in the Getting Help and Contacting Support.	Create brittle consumers that fail abruptly and propagate errors, causing unexpected results, incomplete orchestrations, and operational impact on the hotel.
Orchestrate using the “fetchInstructions” query parameter to retrieve only the needed amount of data. Many of the Oracle Hospitality OPERA Cloud APIs by default return only a subset of a resource or only the parent resource. For example, getProfile returns only the basic information about a person. However, many APIs use a standard query parameter "fetchInstructions," which allows additional, often child, information on the resource to be returned. By tailoring the additional information returned for your use cases, you can enhance API performance and reduce the size of the response body. To achieve this, orchestrate using the "indicators" fetchInstruction that will show which child elements are filled, and then send a call listing only those child elements as fetchInstructions. For example: First call: /crm/v1/profiles?profilesIds={{profileId}}&fetchInstructions=Indicators Then based on the results: Second call: /crm/v1/profiles?{{profileId}}&fetchInstructions=Communication<additional fetchInstructions based upon the results of the first call>	Specify all fetchInstructions on a resource in every API request. This will result in slow performance.
Use the “summaryInfo” query parameter to improve API performance and reduce response body size. This returns only a summary of the resource, not all child elements. For example: /roomTypes?summaryInfo=true	Not using the “summaryInfo” parameter where the summary contains sufficient information. This will result in slow performance.
Using OPERA Cloud as middleware to transfer yield updates sent by an external system to another external system.	Using the “publisher” feature of Business Events on external systems in OPERA that supply yield updates. Yield systems supply OPERA Cloud with updated rates to optimize price per room. This requires sending a large amount of price adjustments, each of which triggers many business events. By default, changes made by one external system are not pushed to another external system. The "publisher" feature within OPERA Cloud enables this to be overridden. However, the "publisher" feature must not be enabled on external systems in OPERA that supply yield updates because this will flood other external systems with needless rate updates and impact the timeliness of sending unrelated business events to those external systems. It will also affect the performance of both OPERA Cloud and all external systems connected to that environment.
Ensure you understand the scope of APIs before using them. Consult the API specifications, Postman samples, and Implementation Guides.	Using APIs beyond their stated scope can result in unexpected errors.
When creating external systems in the OPERA Cloud user interface, configure the Business Events, but mark the external system inactive. Activate the external system only once the consuming architecture is ready. Similarly, subscribe to business events through the streaming API only when the consuming architecture is ready.	Enabling business events for an external system in OPERA or in OHIP ahead of being ready to consume. As soon as an external system is subscribed to business events in OPERA — be it from the OPERA Cloud user interface or OHIP — the subscribed events will start to be enqueued. If not consumed, this will result in a large queue, which is challenging for consuming systems to process. Further, if the external system sends responses back to OPERA Cloud as a result of events received and is slow to process the events, then operational impact can occur as the state of the data in OPERA Cloud would differ from the state of the data perceived by an external system that is running behind.
Before calling payment APIs, first contact the environment owner and ask them to allocate a cashierId to your organization. Use only this provided cashierId when calling payment APIs.	Use any cashierId in payment APIs. The cashierId usually represents a person at the front desk, but since it is possible to make payment changes using APIs, it is important to tie back the change to the organization or user who made the change. When multiple organizations use the same cashierId, it hinders auditing payments.
Use Oracle Hospitality Reporting and Analytics for General Ledger or other financial queries.	Using Property APIs to run General Ledger or other financial queries. Ledger balances and Trial balances are not available through Property APIs. The result of End of Day calculations is not available through Property APIs. This can cause revenue recognition dates for postings retrieved from the Property APIs to be inaccurate due to when End of Day runs. Financial postings are final only after End of Day has run and are not reflected in the Property APIs. A mapping between transaction codes and chart of accounts is not available in Property APIs. Room revenue is split based upon market segment. The Property APIs can obtain information only at the time of the API request. Since this information changes daily due to changes in rates, additional logic must be applied on top of Property API responses to apply the correct market segment to a live transaction.
Ensure that code consuming responses from Oracle Hospitality Property APIs treats header keys as case insensitive.	Code that breaks if the casing of response values changes.
Use Streaming to consume Business Events from OPERA.	The polling API has several limitations, especially in the initial setup.
Include the header X-Request-Id and specify a GUID for its value. This can help Oracle troubleshoot API queries.	You should avoid relying on dates and times because timezones and clock synchronization issues can affect the dates and times that API calls were sent.