Kognitiv Loyalty Web Services (Kognitiv Loyalty-WS) allow our clients and their vendors to integrate their own business solutions with the data and functionality of Kognitiv Loyalty. Kognitiv Loyalty-WS provide a rich interface that makes it extremely easy for developers to build highly effective websites and applications. Kognitiv Loyalty-WS have an open Application Programming Interface (API) that exposes a large set of methods for developers to use in building their solutions. The API is implemented as a series of collections that expose methods related to a particular class of business objects. For instance, functions related to managing loyalty member information are found in the Member collection. Each collection has it own Web Service Definition Language (WSDL) file, which describe the methods associated with that business object.
The Web Service Calls page provides documentation for all of our available "WS" calls, while the REST API Resources page details our RESTful APIs.
What is a Web Service?
This document assumes that you are familiar with using your computer (the client) to request that some other computer (the server's) perform some task and respond over the Internet. The work performed server is called a service. The service might be returning a map location, or, in the case of Kognitiv Loyalty-WS returning information about loyalty members. A web service is any piece of software that uses REST and/or a standardized XML messaging system like SOAP to exchange data between applications or systems. The data is exchanged between systems via standard network protocols, such as HTTP or HTTPS. Software applications written in various programming languages and running on various platforms can use web services transparently to exchange data over computer networks, like the Internet, because the WSDL provides a standard definition of the data that is exchanged.
Web Services vs. "WS" vs. "API"
In Kognitiv Loyalty, there are three generations of web services referred to as "Services", "WS" and "API". The first two generations are based on standardized SOAP XML, with the latter WS supporting JSON and CORS, and providing easier security configuration and enhanced logging via the WS Security Token and WS Log pages. The latest, "API" is based on the REST architectural style. The menu items within the Web menu are named in such a way to reflect their relevance to each of the three generations.
WS Security Configuration
System Location: Web / Services / WS Security Tokens
For the WS calls, all security configuration is performed within the WS Security Tokens page. The three checkboxes for each call configure permissions, basic logging, and logging with input parameters (in that order). It is highly recommended that logging is used only for testing and is disabled in a "live" production environment.
If the token is configured as a template token, then this token can only be used to create temporary tokens.
Temporary Token
WS security tokens configured as a template token type can be used to generate temporary tokens which can be used to make WS calls. Creation of a temporary token will require clients to utilize Google Authenticator technology to attain a TOTP token using the appropriate details on the WS Security Tokens page. These temporary tokens can be created with the GenerateTemporaryToken call and inherit the same role permissions as its template. Furthermore, they will expire after a predetermined amount of time.
Member Temporary Tokens
Furthermore, WS security tokens configured as a template token type can also be used to generate member temporary tokens which can be used to make WS calls. These member temporary tokens can be created with the GenerateMemberTemporaryToken call and inherit the same role permissions as its template. Furthermore, they will expire after a predetermined amount of time. This token is bound to a specific member, regardless of member Id information that is provided as input for the relevant WS calls.
API Security Configuration
System Location: Web / Services / Api Security Tokens
For the REST API calls, all security configuration is performed within the Api Security Tokens page. The four checkboxes for each resource are used to configure permissions.
WS Log
System Location: Web / Services / WS Log
The WS Log page displays the timestamp for each WS Call, the duration, its web service security token name, the associated Web Service and Method, Calling IP, Return Code and details.
The Calling IP column displays the IP address that originated the WS Call. It's possible for the Calling IP column to display multiple IPs when the WS Call moves through a proxy server. When more than one IP displays, the first IP address is the origin while the latter belong to the proxy servers they pass through.
By default, this log page will log erroneous calls. However, within the WS Security Tokens page, additional logging can be configured by token, call, and detail.
KLS allows for the ability to configure and retain a fixed number of Web Service Log entries, and to auto-delete log entries in excess of the configured amount on a weekly basis. This process is executed each Monday and the default value of the number of records to retain is 4,000,000. Contact the KLS Service team to request higher or lower data retention, if required.
See Also
Kognitiv Loyalty Pre-WS Security Token
Kognitiv Loyalty Pre-WS Services Map
