Get started with KPS

This topic explains how to develop an example KPS table for managing simple user information.

Example KPS table

The final structure of the example table is displayed in Policy Studio as follows:

Getting Started - User table in Policy Studio

This table structure is described as follows:

Example table data is displayed on the SettingsKey Property Stores tab in the API Gateway Manager web console:

Getting Started - sample User data in KPS browser

Before you begin

The following prerequisite steps apply to this example:

  1. Ensure that an API Gateway and an Admin Node Manager are running.
  2. Start Policy Studio, and connect to the Admin Node Manager.

For more details, see the API Gateway Installation Guide.

Define KPS configuration with Policy Studio

The main steps for configuring KPS tables in Policy Studio are as follows:

Step 1: Define where data will be stored

You must first create a KPS collection in which to store the KPS table configuration. Perform the following steps:

  1. In the Policy Studio tree, select Environment Configuration > Key Property Stores, then select Add KPS Collection.
  2. KPS collection with the default Embedded (Cassandra) data source
  3. In the Add KPS Collection dialog, name the collection Samples.
  4. Add KPS Collection dialog
  5. Select a Default data source of Cassandra for all tables in the collection.
Note   Leave the Alias prefix field blank.

Step 2: Define the KPS table

To create a table, perform the following steps:

  1. In the Policy Studio tree, right-click the newly-created Samples collection, and select Add Table:
  2. Add Table menu option
  3. In the dialog, enter a Name of User, and provide a Description.
  4. Click Add to assign an alias of User to this table. A table must have at least one alias.
  5. KPS table configuration - specify an alias
  6. Next define the table structure. This consists of the table columns and the data type stored in each column. Select the User table and Structure tab, and click Add:
  7. KPS table configuration - specify table structure
  8. Repeat to add the following columns for your table structure in the Add Property dialog:
    • email
    • password
    • firstName
    • lastName
    • age
Note   age has an Integer (numeric) Type. All the other columns are String. For more details, see KPS table structure.
  1. When you select the User table, you should have the following structure:
  2. Column structure of the User KPS table
  3. You want the email field to be the primary key for the table, so select Primary Key for this field.
  4. Set the email column to be a primary key
  5. You want the password field to be encrypted when stored in the data source, so select Encrypted for this field.
  6. Set the password column to be encrypted

Step 3: Define a policy that accesses the table

To define a test policy that accesses the table, perform the following steps:

  1. Add a test policy with a Set Message filter from the Conversion filter category.
  2. Test policy to access the table
  3. Right-click the filter and set it as the Start filter for the policy.
  4. Enter a filter Content-Type of text/plain.
  5. Enter the following Message Body for use in the policy:

These settings are displayed as follows in the Set Message filter:

Set Message filter settings

The message body value are specified using selectors, which are evaluated and expanded dynamically at runtime. For example, the user age is specified using the following selector string:

The selector parts are explained as follows:

Selector part Description

${

Indicates the start of the selector using a { bracket.

kps

Specifies that selector should query a KPS table.

.User

Specifies the alias of the table to query (in this case, User).

[

Indicates the start of a table property reference using a[ bracket.

http.querystring.id

This is a dynamic query based on an HTTP query string parameter of id. The primary key value is retrieved from this parameter. The row with this key value is returned from the User table if it exists.

]

Indicates the end of a table property reference using a ] bracket.

.age

Retrieves the age column.

}

Indicates the end of the selector using a } bracket.

Note   Add a Reflect Message filter (Conversion category) to return a successful HTTP response status of 200.
  1. Set up a path to this policy. In this example, the path is /kpsGetViaSelector:

Create a path to the test policy

Step 4: Deploy the configuration

When you are finished with your configuration changes, you must deploy them to the API Gateway. To deploy the new configuration, click Deploy in the Policy Studio toolbar:

Deploy the configuration

This pushes the configuration to the API Gateway group.

Tip   If you deploy an incorrect configuration (for example, specify an incorrect primary key, property type, or name) you can use the kpsadmin command to drop the table in storage. For more details, see Manage KPS using the kpsadmin tool.

Add KPS data using API Gateway Manager

You can use API Gateway Manager to populate the User table with data.

For example, perform the following steps:

  1. To access API Gateway Manager in your browser, go to https://localhost:8090.
  2. Select the Settings > Key Property StoresSamplesUser table.
  3. To enter new records, select Actions New Entry on the right.
  4. Click Save to save a record.

For example, the table should look as follows:

KPS browser showing sample record

Access KPS data from a policy

To access KPS data from a policy, go to the following URL in your browser:

This URL specifies the user ID (email) as patrica.allen@acme.com

You must specify an email that exists in your data. For example:

Sample policy execution

Note   If you enter an email that does not exist, you will see [invalid field] results. For example:

Sample policy execution - unknown primary key (email)

Enable API Gateway tracing

To enable API Gateway debug tracing, perform the following steps in Policy Studio:

  1. In the tree on the left, select Environment Configuration > Server Settings > General.
  2. Select a Tracing level of DEBUG.
  3. Click Save.
  4. Click Deploy.

Enable debug tracing

Note   This setting enables debug tracing for the entire API Gateway, and not just for the KPS.

For more details on API Gateway tracing and logging, see the API Gateway Administrator Guide.

Related Links