Using the Paging Policy

Learn how to configure XPath expressions in a Paging Policy to manage the paging of results in web service responses.

For information about using policies in the context of the Community Manager developer portal, see Business Policies.

Table of Contents

Introduction

The Paging Policy is designed to allow a client to request a subset of a list for a list-based response. For example, if an operation returns a list of books, and there are 1000 books in the full list, the client might want to request 100 books at a time rather than the full list.

This policy applies to both SOAP and RESTful (XML) services. When the policy is attached to an operation, the client can request subsets of the list. The document structure around the list is returned with every response, but only a subset of the actual books. Notes:

  • For REST services, the client requests the subset of items by providing two query parameters: index and count.
  • For SOAP messages, two SOAP headers are provided: {http://federatedgovernance.org/policy/paging}Index and {http://federatedgovernance.org/policy/paging}Count.
  • The index parameter/header is the row number of the full list that should be returned as the first item to the current request.
  • The count parameter/header indicates how many rows should be returned.

Determining what is a row of the response is specified in the Paging Policy. An XPath expression is used to identify what a row is in the XML document. The XPath expression will be evaluated against the full response, which should result in a list of elements. The list of elements returned by the XPath expression is filtered by the index and count properties as described above.

Configuration Options

The policy includes the following configuration options:

  • Item XPath: Used for entering an XPath expression.
  • Namespace Prefixes Table: Holds a list of namespace prefix definitions used in the XPath expression in the specified Item XPath. Includes columns for specifying Prefix used in the XPath, and Namespace associated with the Prefix.
  • Add: Adds an empty row to the Namespace Prefixes table.
  • Remove: Remove the selected row from the Namespace Prefixes table.

Configuration

Let's take a quick walkthrough of the Paging Policy configuration process to get you started.

Step 1: Add Policy

In Policy Manager, to create a Paging Policy instance, go to Policies > Operational Policies and choose Add Policy.

Step 2: Modify Policy

When you click Modify to make changes to the Paging Policy on the Policy Details page, the initial policy looks like this:

Add the desired XPath and Namespace information (for example, //*[local-name()='result']):

Step 3: Create Physical Service and Virtualize

  • Create a physical service.
  • Virtualize and host it on Network Director (Example service name: Vs1).

Step 4: Attach Policies

  • Attach Detailed Auditing and Paging policies to the virtual service.

Step 5: Configure Paging Policy

  • Create a project in SOAP UI and send requests to the virtual service.

    SOAP Request Message:

    SOAP Response Message:

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

To use the policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.