5 Web Services in Retail Applications

This chapter gives an overview about the Allocation ReSTful Web Service Implementation and API designs used in the Allocation environment. Retailers can access back-end 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: 15.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
Allocations

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

Allocations

This section covers the following:

Approve
Load Recent Allocations by User
Load by Query
Load by Allocation ID
Load Item Location Information
Lookup Allocation Status
Lookup Process Status
Reserve
Submit
Withdraw

Approve

Business Overview

REST endpoint for approving an allocation.

Service Type

Post

ReST URL

/Allocations/approve

Parameter(s)

AllocationRDO - {"id": Value}

Returns

No content response.

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER

Load Recent Allocations by User

Business Overview

REST endpoint for loading recent allocations of logged in user.

Service Type

Get

ReST URL

/Allocations/recent/{records}

Parameter(s)

records - number of records to return

Returns

A collection of AllocationRDO

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER, BUYER

Load by Query

Business Overview

REST endpoint for loading allocations that satisfy the supplied criteria.

Service Type

Get

ReST URL

/Allocations?dept={dept}&class={class}&subclass={subclass}&id={id}&status={status}&allocStatus={allocStatus}&createdDate={createdDate}&createdBy={createdBy}

Parameter(s)

dept - department of the items within an allocation
class - class of the items within an allocation
subclass - subclass of the items within an allocation
ID - comma separated allocation IDs
status - the process status of an allocation
allocStatus - the status of an allocation
createdDate - created date of an allocation in yyyy-MM-dd format
createdBy - userId information of the user who created allocation

Returns

A collection of AllocationRDO

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER, BUYER

Load by Allocation ID

Business Overview

REST endpoint for loading allocation header based on allocation id.

Service Type

Get

ReST URL

/Allocations/{id}

Parameter(s)

id - allocation id

Returns

A collection of AllocationRDO

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER, BUYER

Load Item Location Information

Business Overview

REST endpoint for loading item location information based on supplied information.

Service Type

Get

ReST URL

/Allocations/{id}/itemloc?facetSessionId={facetSessionId}&allocType={allocType}&itemId={itemId}&whId={whId}&docType={docType}&docId={docId}&diffDescription={diffDescription}&diffTypeId={diffTypeId}

Parameter(s)

ID - allocation ID
facetSessionId - facet session ID associated with the allocation. This ID is generated from a loaded allocation.
allocType - type of allocation. Acceptable values: SA, FA, or FPG.
itemId - item ID
whId - warehouse ID associated with the item
docType - source type where the item is source from. Acceptable Values (PO, ASN, OH, WHIF, BOL,TSF)
docId - source order number
diffDescription - diff description retrieved from allocation details service
diffTypeId - diff type ID retrieved from allocation details service

Returns

A collection of ItemLocRDO

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER, BUYER

Lookup Allocation Status

Business Overview

REST endpoint for looking up allocation statuses.

Service Type

Get

ReST URL

/Allocations/allocStatus

Parameter(s)

None

Returns

A collection of LookUpRDO

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER, BUYER

Lookup Process Status

Business Overview

REST endpoint for looking up process statuses.

Service Type

Get

ReST URL

/Allocations/status

Parameter(s)

None

Returns

A collection of LookUpRDO

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER, BUYER

Reserve

Business Overview

REST endpoint for reserving an allocation.

Service Type

Post

ReST URL

/Allocations/reserve

Parameter(s)

AllocationRDO - {"id": Value}

Returns

No content response.

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER

Submit

Business Overview

REST endpoint for submitting an allocation.

Service Type

Post

ReST URL

/Allocations/submit

Parameter(s)

AllocationRDO - {"id": Value}

Returns

No content response

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER

Withdraw

Business Overview

REST endpoint for withdrawing an allocation.

Service Type

Post

ReST URL

/Allocations/withdraw

Parameter(s)

AllocationRDO - {"id": Value}

Returns

No content response.

Allowed Job Roles

ALLOCATOR, ALLOCATION_MANAGER