Get Request and the Show Response

Search expressions for Get service request

Following the OAGIS model for read requests, the best practice is for every read request to be represented as a Get Noun document where Get is the action to perform and the Noun is the business object or objects to return. As a response to the Get request, the Show document will be returned with the requested data.

The search expressions will be XPath expressions which represent a query against the respective noun to indicate the data to be returned. As part of the extension to the XPath syntax, there is a way to pass control information to indicate the amount of data to return, ordering and other search result control information.

Read requests will use XPath expressions to define the response data to be returned.

Access profile

An access profile can be used to scope the response data. For example, to return a specific view of the data (for example a search view of a catalog entry), or to return the data in all languages for authoring purposes. As an extension to the XPath syntax, the access profile name-value pair should be prepended to the XPath expression in curly brackets ({}). You must always specify the access profile. For more information, see WebSphere Commerce extended XPath notation.

{_wcf.ap=$accessProfile$}/CatalogGroup[Name='MyCatalogGroupName']

Result paging

There are cases when the results need to be paged so the service request will only return a subset of the data that matches the criteria. To control the amount of records to return, the GET verb has paging attributes which will be used to indicate the number of records to return and where to start from on the list of information to return. The maxItems attribute is used to indicate the number of data elements returned from the query and recordSetStartNumber is the starting index of the record set to start returning information.

For search expressions where the number of returned results does not equal the number of possible results of the query, the responding Show message will populate the recordSetReferenceId attribute. This attribute can be used by the client as a key to uniquely identify the query in order to avoid performing the entire search again. The recordSetReferenceId is a unique key associated with the search that will only be valid for a timeout period which is dependent on the component facade implementation. The service consumer can use this identifier as an indicator to the component facade implementation that it should retrieve cached results instead of re-running the expression just to return a different page of the same results.

Below is an example of the Show verb response and the next Get verb to retrieve the next 10 elements of the query. As a result of the Show response, the recordSetReferenceId is populated along with the number of records the query returned and the number of records included within the current response message. The preceding GET request can use the recordSetReferenceId to retrieve the next page of records to avoid the server to re-execute the query.

<oa:Get maxItems="10" recordSetStartNumber="10"
  recordSetReferenceId="ABCD-1234-WXYZ">
  <oa:Expression expressionLanguage="_wcf:XPath">
   
{_wcf.ap=$accessProfile$}/CatalogGroup[Name='MyCatalogGroupName]
  </oa:Expression>
</oa:Get>

<oa:Show
  recordSetCompleteIndicator="true"
recordSetReferenceId="ABCD-1234-WXYZ"
  recordSetTotal="101" recordSetCount="10"
recordSetStartNumber="10">

Pagination for complex nouns

OAGIS only supports pagination at the noun level. The data service layer and SOI components do not support paging on sub nouns. However, there are nouns within nouns, known as sub nouns, that also need to be paginated (for example, OrderItem, within the Order noun) in the Order component.