Understanding the Configuration and Content API

The Configuration and Content (C&C) API lets you Create, Read, Update, and Delete Simphony configuration database records. The Enterprise Management Console (EMC) and the Import/Export API also manipulate these records. To ensure the highest possible performance, the API provides records in the rawest possible format.

Use Cases

The API supports the following use cases:

System to system integrations
Custom configuration interfaces
Bulk data imports for new locations

System to System Integrations

A typical example of this use case is integrating inventory and production management solutions with Simphony so menu items can be creating in the external systems and published to Simphony. These systems have their own configuration databases and sync data with Simphony on a either an as needed or timed interval basis.

Custom Configuration Interfaces

This solution involves creating a user interface that is constantly reading and writing via the API. In this case, there is no intermediate datastore which the application interacts with that synchronizes with Simphony later. The user experience relies heavily upon API performance.

Bulk Data Imports

When first configuring a system for the first time or rolling out new locations over, there can be a need to insert many menu items. There are API endpoints that can process thousand of records at a time, which is much more efficient that making individual API insert calls.

Performance

The database which contains Simphony’s entire configuration lies beneath the API. This database is used by all components of the system that consume and synchronize configuration data. To maintain optimal system performance, the system limits API usage as follows:

Product Edition/Environment	Usage Maximum
Simphony Cloud Service, Single-Tenant Edition	9 API calls per second for the environment.
Oracle Hospitality Simphony Standard Cloud Service, Non-Production Environment	1 API call per second for each enterprise.

Since the API supports calls of varying complexity, it is possible to exceed these values if the calls are small enough. For example, a request which returns 10,000 records takes longer to process than a request to insert a Menu Item Price record.

If a request runs into a guardrail, the API returns either a 429 or 503 status code. If that status code is received, retry the request in a few seconds.

API URL Structure

There are two API URL formats:

base_URL/service_type/sim/API_version/subject_area/API_endpoint
base_URL/service_type/sim/API_version/subject_area/endpoint/sub-API_endpoint

The following table describes the URL components:

Component	Description
`base_URL`	The base URL for a Simphony environment can be found within the EMC Enterprise Parameters module. Example: `https://mtu03-ohsim.oracleindustry.com`
`service_type`	Values: `Config` - for accessing database records `Content` - for manipulating content data (for example, image files)
`API_version`	Example: `v1`
`subject_area`	Values: `Devices` - APIs that maintain devices (for example, workstation and KDS clients). `Employees` - APIs that maintain the users (for example, operators and cashiers). `Hierarchy` - APIs that maintain the hierarchy and hierarchy units (properties, locations, and zones). `Menu Items` - APIs that maintain the menu items. `Others` - Utility APIs (version, status). `Sales` - APIs that maintain transaction related items (for example, discounts, service charges, and tenders). `Setup` - APIs that maintain non-sales or menu related items (for example, order channels and order types).
`API_endpoint`	The API action.
`endpoint`	If the API endpoint contains nested subject areas, this value is used to drill down to the sub-API endpoint.
`sub-API_endpoint`	These exist for complex APIs which return data from multiple tables so that smaller datasets and targeted changes can be made.

Considerations

Consider the following points when using the API:

If someone is editing records in the EMC while API activity is occurring in the same area, the last operation completed regardless of its origin (EMC or API) is reflected in the system.
The API is a database CRUD tool and does not contain the application logic found within EMC, which provides guidance on which feature or option combinations are compatible.
Use the EMC to understand the data within a record by using the API to retrieve a record, changing the record with EMC, retrieving the record, and observing the results.