Common Characteristics

Security

Services are secured using J2EE-based security model.

Realm-based User Authentication: This verifies users through an underlying Realm. The username and password are passed using HTTP basic authentication.
Role-based Authorization: This assigns users to roles; authenticated users can access the services with Merchandising or Sales Audit application roles or custom roles that are assigned to:
- For Merchandising MERCH_SERVICE_ACCESS_PRIV
- For Sales Audit MERCH_SERVICE_ACCESS_PRIV
The communication between the server and client is encrypted using one-way SSL. In non-SSL environments the encoding defaults to BASE-64 so it is highly recommended that these ReST services are configured to be used in production environments secured with SSL connections.
If you are using Merchandising data filtering, that will apply to the services as well. The user ID used for the calling the service should be added to the Merchandising SEC_USER table (APP_USER_ID), and then associated to the appropriate group in SEC_USER _GROUP table. For more information on this see the Merchandising Security Guide - Volume 2.

Standard Request and Response Headers

Merchandising and Sales Audit ReSTful web services have the following standard HTTP headers:

   Accept: application/xml or application/JSON
   Accept-Version: 16.0 (service version number)
   Accept-Language: en-US,en;q=0.8

Note:

Accept-Language is not mandatory, and defaults to en-US. The user can change it though; in case they need content in a specific language. The language support in the response payload is limited to a selective service which was created for the mobile client use case.

Depending on the type of the operation or HTTP method, the corresponding response header is updated in the HTTP response with the following codes:

GET/READ : 200
PUT/CREATE : 201 (Created) or 200 (Success)
POST/UPDATE : 204 or 200 (Success)
DELETE : 204 or 200 (Success)

Standard Error Response

Example response payload in case of service error is depicted below:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <messagesRDOes>
     <messagesRDO>
        <message>REST Service Version Mismatch</message>
        <messageType>ERROR</messageType>
        <status>BAD_REQUEST</status> 
    </messagesRDO>
   </messagesRDOes>

Message: The error message - translated.
Message Type: Value of 'ERROR' is returned.
Status: For a bad request or error, the status is BAD_REQUEST.
The http error code for an error response is 400.

Merchandising URL Paths

Based on your implementation you will need to prefix the end point with just the deployment hostname. The format that should be used for the hostname is rex.retail.<Region Name>.ocs.oraclecloud.com/<Customer Subnamespace>/, where <Region Name> will be the region for your data center and <Customer Subnamespace> will be specific to your company’s name and environment (production, stage, and so on).

The Merchandising services are hosted on two separate application servers. The application server named MerchIntegrations contains new Integration web services for data publishing and subscription. The RmsReSTServices contains other, legacy web services.

The following links provide access to the Merchandising services:

The ReSTful Web services swagger URL is available at:

https://<hostname/namespace>/RmsReSTServices/swagger-ui/

https://<hostname/namespace>/MerchIntegrations/swagger-ui/
The ReSTful Web services openapi.yaml is available at:

https://<hostname/namespace>/RmsReSTServices/services/openapi.yaml

https://<hostname/namespace>/MerchIntegrations/services/openapi.yaml
The ReSTful Web services’s WADL file is available at:

https://<hostname/namespace>/RmsReSTServices/services/private/application.wadl

https://<hostname/namespace>/MerchIntegrations/services/application.wadl
The ReSTful Web services are available at:

https://<hostname/namespace>/RmsReSTServices/services/private/<service>

https://<hostname/namespace>/MerchIntegrations/services/<service>

Sales Audit URL Paths

Based on the Implementation you may need to prefix the end point with just the deployment hostname or hostname plus access port.

The following links provide access to the Sales Audit services:

The ReSTful Web services swagger URL is available at:

https://<hostname/namespace>/ResaReSTServices/swagger-ui/
The ReSTful Web services openapi.yaml is available at:

https://<hostname/namespace>/ResaReSTServices/services/openapi.yaml
The ReSTful Web services’s WADL file is available at:

https://<hostname/namespace>/ResaReSTServices/services/private/application.wadl
To access the ReSTful web services:

https://<hostname/namespace>/ResaReSTServices/services/private/<ResaService>

Fiscal Document Generation URL Paths

Based on your implementation you will need to prefix the end point with just the deployment hostname. The format to be used for the hostname is xxx-yyy-mfcs-rhs.oracleindustry.com, where xxx-yyy is specific to your company's name and environment (production, stage, and so on). The following links provide access to the Fiscal Document Generation services:

The ReSTful Web services Javadocs are available at:
```
https://<hostname>/RfmReSTServices 
```

The ReSTful Web services's WADL file is available at:

https://<hostname>/RfmReSTServices/services/private/application.wadl

The ReSTful Web services are available at:

https://<hostname>/RfmReSTServices/services/private/application.wadl

OAuth for REST Service Authentication

OAuth 2.0 is the industry standard protocol for authorization. Merchandising cloud services REST Services now supports OAuth 2.0. To invoke these services, you need to obtain and access token and use it as a bearer token.

Note:

Basic Authentication access is no longer supported for these services. Allocation Cloud Service will still use Basic Authentication with this release.

Steps to Enable

To obtain a token and call the services, use the following steps:

This step should be performed one time for a given environment. Generate OAuth Client App with the environment-specific scope.

Each environment has a different scope that is available after the provisioning of the environment. Use this scope to generate the OAuth Client App using the Retail Home UI. For details, refer to the ”Creating OAuth Client Apps” section of the Retail Home Administration Guide, which can be found under Common Cloud Services Solutions in the Oracle Retail Help Center. Once the OAuth Client App is generated, note the client ID and secret. This information will be required for an access token to call REST services.

Get an access token using the OAuth client ID and secret from IDCS.

export ACCESS_TOKEN="$(curl -u <Client ID>:<Secret> -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<IDCS_BASE_URL>/oauth2/v1/token -d 'grant_type=client_credentials&scope=<Customer Environment Specific Scope>' | jq -r '.access_token')"

The token is generally valid for 1 hour.

REST clients that need to call Merchandising REST service end points should use the client ID and secret of the OAuth client generated in the previous step to get an access token.

OAuth tokens can also be obtained by REST client tools like Postman for testing purposes by filling in the necessary details like client ID/secret and scope. Use the below information in such cases:

Authorization: OAuth 2.0
Access Token URL: https://<IDCS_BASE_URL>/oauth2/v1/token
Client ID: <Client id of OAuth client app>
Client Secret: <Client secret of OAuth client app>
Scope: <Custom environment specific scope>
- The scope pattern that is used in the MFCS IDCS app creation template is rgbu:merch:<SERVICETYPE>-<ENVIRONMENT> where SERVICETYPE is MFCS and ENVIRONMENT is the environment type (STG, PRD, UAT, DEV1, DEV2, and so on).
  
  For example:
  - "scope": "rgbu:merch:MFCS-PRD"
  - "scope": "rgbu:merch:MFCS-STG"

Example using the access token as a bearer token:

curl --location --request GET 'http://<hostname or IP address>:<port number>/ RmsReSTServices/services/private/Common/vDate' \ --header 'Authorization: Bearer $ACCESS_TOKEN'

Date Format

Few input date and output date fields are in long format. The others are in SQL Date format. The new MerchIntegrations service supports dates in the yyyy-mm-dd format and datetimes in the yyyy-mm-ddTHH24:Mi:SS.SSSZ format.

Limited Availability During Nightly Batch Cycle

Several of the consume ReST services can interfere with batch jobs running during the MFCS nightly batch window. To avoid data processing conflicts, several ReST services are either not available during the entire duration of the nightly batch window or unavailable for a portion of the nightly batch. These services will fail with a 400 error if they are invoked during the window of unavailability.

The availability of the Rest services is categorized as:

Available 24/7 – These services are available 24/7 except for the time during which the application is being patched. Most services are available 24/7 and this includes all the GET services and most of the foundation data setup.
Not available during entire nightly batch – A small set of services are not available during the entire window of the nightly batch cycle. This includes services that are only active on certain dates (like stock count schedule, cost changes) or services that can influence the business logic of several jobs (like update item, item/supplier, store, reclassification, and so on).

The POM job START_BATCH_JOB disables these services by setting the value of batch_running_ind to Y in the rms_batch_status table. The POM job END_BATCH_JOB switches the indicator back to N and the services are then available to process the data.
Not available during Inventory batch window - The web services that impact inventory buckets are not available during portions of the nightly batch during which inventory-related batch processes are running. This includes the services related to the functionality of receipts, transfers, allocations, inventory adjustment, customer orders, and so on.

The POM job STOP_RIB_ADAPTOR_INV_JOB disables these services by setting the value of inventory_batch_running_ind to Y in the table rms_batch_status. The job START_RIB_ADAPTOR_INV_JOB switches the indicator to N to reenable the services.
Not available during Costing and Inventory batch window – Some of the services interfere with (in addition to impacting) the inventory buckets, which also impacts the cost component and expenses. These services are not available during the inventory batch window (inventory_batch_running_ind = Y) and while costing batch jobs are running at the initial phase of the nightly batch. This includes services related to functionality of purchase orders, item expenses, item HTS, supplier updates, exchange rate updates, and so on.

The POM job DUMMY_START_NIGHT_BATCH_JOB disables these services during the costing batch window by setting costing_batch_running_ind to Y in the rms_batch_status table. The job END_COSTING_BATCH_JOB switches the indicator to N, which reenables the services once the costing batches are complete.

Note:

MerchIntegration services having limited availability during nightly batch have a custom property named x-batch-dependency in the openapi.yaml file.

Custom HTTP Headers

The Rest Service supports custom HTTP Headers that can be used to exchange additional metadata about the service calls. These are:

X-Correlation-ID: The client can include a unique ID in the HTTP header “X-Correlation-ID” to uniquely trace the service call. The input X-Correlation-ID is captured in server logs and in the service_metrics table to provide details of the outcome of the service call. While the expectation is that the client should have a unique correlation ID in every request, the uniqueness is not validated by the ReST service.

In the response HTTP header, X-Correlation-ID is always included. If the request HTTP header contains a X-Correlation-ID, the same value IS returned in the response HTTP header. If the input header is missing the correlation id, a server generated request id (UUID) IS populated in the response X-Correlation-ID header field. The server generated request ID is captured in service_metrics table.

Best Practice – The client should generate a UUID (up to 36 bytes) and include the UUID in the request in the HTTP header X-Correlation-ID and persist the ID in some data store for traceability purposes. In case of exceptions or troubleshooting, this ID is handy when checking the table service_metrics for how the server processed the request.

Example usage: The client makes a call and the client crashes before the response is received, or there was timeout thrown by one of the infrastructure components between the client and the application server (like load balancer or routers). The correlation ID can be checked in the table service_metrics to identify the actual response. If the service method is POST or PUT or DELETE, the table service_payload can be referenced to get the response payload for that request.

Note:
Capturing X-Correlation-ID in server logs or in the table service_metrics is done by the ReST Service application server and the request should have arrived at this server for the service request to be logged. The application server captures the request in the service_metrics table when the request is received. After the request is processed, the server updates the same row in the service_metrics table to capture the response status.
X-Client-Principal-User: The client can include an optional HTTP Header in the request to provide a business user identifier in a system-to-system service call to allow for capturing the business user that created or updated the content of the request. As part of the service request in which data is created or updated, the audit columns create_id and last_update_id capture the OAuth client name used to make the service call. In the request containing X-Client-Principal-User, this value is used as-is (without any validation) to populate the audit columns.
X-Content-Has-More: This HTTP Header (true or false) is included in the response for several Merch Integration Publish API. The GET services that supports pagination includes the field hasMore in the payload to inform the client if there are additional pages to be requested. This information is also captured in the HTTP Header to allow the client to quickly access this information without parsing the response payload.
X-Content-Offset-Key: This HTTP Header is included in the response, along with X-Content-Has-More, when there are additional pages to be requested for a service supporting pagination using the query parameter offsetkey. The client can use the value from the HTTP Header instead of reading it from inside the payload to construct the URL for the next page.
X-Content-Count: This HTTP Header is included as an additional information in several Merch Integration Publish APIs to inform the client of the number of records in the response payload.

Paging

Some of the Merchandising and Sales Audit ReSTful web services have the potential to bring back a significant number of records, and therefore these services are equipped to segment the result into pages. The page number to retrieve and the size of the page are added as input parameters to all the paged services.

Each paged result includes the following information:

Total Record Count: Displays the number of all records matching the service input criteria.
Next Page URL: Shows the service URL with same input parameters, but with the pageNumber plus 1, when more records exist.
Previous Page URL: Shows the service URL with same input parameters and the pageNumber input value minus 1, when page number is not 1.

Next or previous page URL is not provided when:

No records are returned
Previous page is not returned, when the page number is 1.
Next page is not returned, when the record reaches the last page.

Figure 5-2 Javascript for Paging Information in RMS Web Services

Web Service APIs Process Flow

The diagram shows the Web Service API process flow.

Figure 5-3 Web Service APIs Process Flow

Configuring ReSTful Web Services for Integration with External Systems

Based on your implementation, you will need to enable the Merchandising ReSTful publishing services for data replication between Merchandising and external systems. Additionally, the Omnichannel integration ReSTful services may also be enabled for external consumers. These two enablements are performed through the Web Service Configuration Screen in Merchandising. After a service is enabled, the table triggers will start writing data to respective change log tables and the corresponding background job will start populating JSON cache tables. When a service is disabled, the ReST service will be unavailable, triggers will stop capturing new changes, and background process will clean up the JSON cache table. For details on the Publish API, refer to reference paper Publish APIs - Customer Enablement Overview available in Oracle Retail Merchandising Documentation Library (Doc ID 1585843.1) in My Oracle Support. For more details on how to enable a web service, see the Merchandising Administration Guide.

The below listed services can be enabled or disabled using the Merchandising UI,