KPS API
Overview
The Key Property Store (KPS) provides a consistent interface to object data in heterogeneous data stores.
The KPS REST API is exposed by API Gateways. It must be invoked via the Routing API in the Admin Node Manager.
KPS consists of Types, Stores and Aliases.
Type
A Type defines the set of properties of an object and the type of those properties. For example, EmployeeType could have
three properties, (id, name, age), with types (String, String, Integer).
A Type has a unique ID within an API Gateway Group.
Store
A Store manages a set of objects of a specific Type. For example, EmployeeStore could contain records of type EmployeeType.
A Store also has additional metadata such as the identity of the primary key and the type of storage that
it uses (file, database or Cassandra).
Each Store has a unique ID within an API Gateway Group.
Alias
An Alias is an alternative name for a particular Store.
Aliases are used when referring to a Store via the REST API or in expression language (EL) selectors.
Note: Policy Studio does not show Type information, but only allows Stores and Aliases to be created and modified.
When a new Store is created, a Type of the same name is created automatically. For example, creating a Store called
'Employee' will also result in a new Type called 'Employee'.
Identifiers
| Identifer | Valid Characters |
|---|---|
| Type name | a-z, A-Z, 0-9, underscore, dash, space |
| Type/Store configuration property name | a-z, A-Z, underscore |
| Store name | a-z, A-Z, 0-9, underscore, dash, space |
| Alias | a-z, A-Z, underscore |
Note: Aliases and Type property names are used in EL syntax and so have a more restrictive format.
Types
A Type has a unique ID within an API Gateway Group.
It has a set of one or more properties.
Each property has a unique name within the Type and a property type.
Property Types
Properties are returned as Java Objects when accessed via EL statements on the API Gateway at runtime.
When exchanged with REST clients, properties are encoded in JSON.
The following property types are supported by KPS.
Basic Types
| Type | JSON | Use as Key Field |
|---|---|---|
| java.lang.Boolean | true OR false | N |
| java.lang.Byte | number | N |
| java.lang.Integer | number | Y |
| java.lang.Long | number | Y |
| java.lang.Double | number | N |
| java.lang.String* | string | Y |
*Max String lengths are determined by the underlying storage mechanism.
Collections
| Type | JSON |
|---|---|
| java.util.List |
JSON array |
| java.util.Map<K,V>, where K and V are basic types e.g. java.util.Map<java.lang.String,java.lang.Byte> | JSON object |
Object Creation and Update
Objects must be created, updated and deleted via a primary key.
This key is specified via the Store configuration "key" property.
Objects must be read via the primary key or an optional secondary key.
The secondary key can be a single property or an ordered list of properties.
This key is specified via the Store configuration "readKey" property.
Typically the primary key is used to manage objects in a Store via an internal unique primary key,
and the secondary key provides a user friendly access to the object.
E.g. employee id is an internal hidden UUID, email is a public user-friendly secondary key.
For object creation, both the primary ID and the secondary ID (if defined) must be specified.
For object update, the primary ID must be specified.
Other properties are optional.
To update a property specify its new value.
To delete a property set the value to null.
It is not currently possible to partially update a Map or a List property.
All properties of the Map or List must be specified for this case.
REST API
Schema Methods
| Resource | Description |
|---|---|
| GET /api/kps | Gets the current KPS schema. i.e. configured Types, Stores and Aliases. |
Store Methods
Create, retrieve, update and delete objects in a Store.
| Resource | Description |
|---|---|
| GET /api/kps/{storeAlias}/{objectId} | Gets a Store object. |
| POST /api/kps/{storeAlias} | Creates an object with server side generated id. |
| PUT /api/kps/{storeAlias}/{objectId} | Creates an object with a client side generated id OR Updates an object. |
| DELETE /api/kps/{storeAlias}/{objectId} | Deletes an object. |
| GET /api/kps/iterator/start/{storeAlias}/{batchSize} | Iterates though objects. Start iteration. |
| GET /api/kps/iterator/next/{storeAlias}/{batchSize} | Iterates though objects. Next iteration. |
Search Methods
| Resource | Description |
|---|---|
| GET /api/kps/{storeAlias} | Filters Store objects. |