5 Web Services in Retail Applications

Retailers can access backend functionality in Retail Applications by calling the applications' ReSTful Web Services.Refer to http://www.oracle.com/technetwork/articles/javase/index-137171.html to learn more about ReST as an architectural style applied to building web services.

Common Characteristics of Retail Application ReSTful Web Services

This section describes the common characteristics.

Deployment

A Retail Application will package its ReST services as part of the application's Enterprise Archive (EAR) file. Specifically, those services are packaged as a Web Archive (WAR) within the EAR.

Installation of the ReST web services is therefore done by default.

Security

Services are secured using J2EE-based security model.

• Realm-based User Authentication. This verifies users through an underlying realm. The username and password is passed using Http Basic authentication.

• Role-based Authorization. This assigns users to roles, which in turn are granted or restricted access to resources/services. The authorization of ReSTful web services is static and cannot be reassigned to other rules post installation. The following role(s) is/are associated with ReSTful Web Services and should be added to the Enterprise LDAP:

  All enterprise roles defined above are mapped in web.xml and weblogic.xml of the ReST Service webapp.

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.

Standard Request and Response Headers

Retail Application 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
Accept-Versioning: False 

Note: Specify 'Accept-Versioning: False' in the Service Request to bypass 'Accept-Version' validation on services.

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

• POST/UPDATE : 204

• DELETE : 204

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.

• messageType: 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.

List of ReSTful Web Services

This section covers the following:

• Platform ReSTful Web Services

• REIM ReSTful Web Services

Platform ReSTful Web Services

This section lists Web Services provided by the Retail Fusion Platform.

Notification ReST Services

Service endpoints have been enabled for the Notifications Framework. These endpoints are deployed separately and can be accessed by the following url:

http://server:port/RetailAppsReSTServices/services/private/Notifications/*

The endpoints exposed are detailed below.

Table 5-1 Notification ReST Services

Description	URL	HTTP Method
Creating Notifications	/Notifications/create	POST
Updating Notifications	/Notifications/update	PUT
Deleting Notifications	/Notifications/delete/{id}	DELETE
Fetch Notifications	/Notifications/fetch?appCode={appCode}	GET
Get number of unread Notifications	/Notifications/fetch/unreadCount?appCode={appCode}	GET
Search Notifications	/Notifications/search?appCode={appCode}	GET
Filter Notifications - Return list of Notifications	/Notifications/filter/list	POST
Filter Notifications - Return grouped list of Notifications	/Notifications/filter/group	POST
Filter Notifications - Return a summarized list of Notifications	/Notifications/filter/summarize	POST
Count Notifications matching the filter	/Notifications/filter/count	POST
Persist the Criteria	/Notifications/criteria	POST
Fetch the Criteria	/Notifications/fetch/criteria?appCode={appCode}	GET
Fetch Recipients	/Notifications/fetch/recipients/{id}	GET
Fetch Notification Context	/Notifications/fetch/context/{id}	GET
Fetch Notification Time Periods	/Notifications/fetch/timeperiods?appCode={appCode}	GET
Fetch Notification Hierarchy Levels	/Notifications/fetch/hierarchylevels?appCode={appCode}	GET
Fetch Notification Types	/Notifications/fetch/notificationtypes?appCode={appCode}	GET
Status update for multiple Notifications	/Notifications/update/multiple/status	PUT
Delete multiple Notifications	/Notifications/delete/multiple	POST

Access Control ReST Service

Table 5-2 Access Control ReST Service

Description	URL	HTTP Method
FetchFilteredRoles	/AccessRoles	POST

Favorites ReST Services

Table 5-3 Favorites ReST Services

Description	URL	HTTP Method
Fetch all Favorites	/Favorites/fetch	GET
Add a Favorite	/Favorites/add	POST
Delete a Favorite	/Favorites/delete	DELETE
Update a Favorite	/Favorites/update	POST
Replace a Favorite	/Favorites/replace	POST

REIM ReSTful Web Services

Several services used by the mobile application are exposed via RESTful web services.

Table 5-4 RESTful Web Services

Service Operation	Type	URL
Dashboard	Get	/dashboard
Supplier List	Get	/suppliers?employeeIds=[employeeId Array]&specificSearchValue=[]&numberOfInvoices=[]&supplierIds=[supplierId Array]&sortOrder=[]&screenSort=[]&pageSize=[]&pageNumber=[]
Supplier	Get	/supplier?supplierId=[]
Invoice List	Get	/invoices?employeeIds=[employeeId Array]&invoiceAmountHigh=[]&cashDiscount=[]&screenSort=[]&pageSize=[]&costDiscrepancy=[]&unitDiscrepancy=[]&specificSearchValue=[]&supplierIds=[supplierId Array]&pageNumber=[]&daysOut=[]&invoiceAmountLow=[]
Employee List	Get	/employees?pageNumber=[]&pageSize=[]&screenSort=[]&sortOrder=[]
Employee	Get	/employee?employeeId=[]
Supplier Criteria	Get	/supplierCriteria?pageNumber=[]&pageSize=[]&specificSearchValue=[]
Employee Criteria	Get	/employeeCriteria?pageNumber=[]&pageSize=[]&specificSearchValue=[]