Using the JSON APIs

Using the JSON APIs
Prev	Chapter 24. Programming Guide	Next

The Business and Enterprise Editions of KonaKart offers you the ability to communicate with the KonaKart engines using JSON (JavaScript Object Notation). A servlet receives requests in JSON format over HTTP/HTTPS and passes these on to an application or admin engine that processes the request. The response is returned in JSON format.

By default the JSON Server servlet sections in the web.xml files for the konakart and konakartadmin webapps are commented out so JSON services are disabled after a standard install.

A convenient way to enable JSON services is to run the enable_JSON (or enable_KKAdmin_JSON for the KKAdmin JSON servlet) ANT task provided in the build.xml file in the custom directory of the standard installation as follows:


C:\KonaKart\custom>bin\kkant enable_JSON
Buildfile: build.xml

enable_JSON:

enable_JSON_warning:

enable_JSON_enterprise:
     [echo] Fix konakart web.xml to start-up JSON

BUILD SUCCESSFUL
Total time: 0 seconds

There are two sections in the konakart and konakartadmin webapp's web.xml files to modify to enable the JSON server. (In this explanation we refer only to the konakart webapp's web.xml but the same is applicable to the konakartadmin webapp web.xml for the KKAdmin JSON servlet set-up). The first is the servlet definition and the second is the servlet mapping. To enable the JSON Server servlet section you must uncomment the definition in the konakart webapp's web.xml file shown below:


<!-- JSON Server --> 
<servlet>
		<servlet-name>KonaKart_JSON_Servlet</servlet-name>
		<display-name>KonaKart JSON Server</display-name>
		<description>KonaKart JSON Server</description>
		<servlet-class>
			com.konakart.json.KKJSONServer
		</servlet-class>
		<init-param>
			<param-name>jsonEnabled</param-name>
			<param-value>true</param-value>
		</init-param>
		<init-param>
			<param-name>includedInterfaces</param-name>
			<param-value></param-value>
		</init-param>
		<init-param>
			<param-name>excludedInterfaces</param-name>
			<param-value></param-value>
		</init-param>
		<load-on-startup>30</load-on-startup>
</servlet>

Note the availability of the two JSON servlet parameters: "excludedInterfaces" and "includedInterfaces". These can be used to fine tune the JSON services that you make available from your system. It is recommended that you only make available those interfaces that are required by authorised client applications. In both cases (excludedInterfaces and includedInterfaces) you simply specify a comma separated list of KKEngIf interfaces that are to be allowed or disallowed. For a list of KKEngIf interfaces available in your version of KonaKart you will find a list in the comments in the server-config.wsdd file in your konakart/WEB-INF/ directory after a standard installation (provided from version 6.3.0.0). See the web.xml for the konakart webapp for more details. (See also the web.xml for the konakartadmin webapp for details for the KKAdmin JSON servlets).

Next, to enable the servlet mapping, you must uncomment the definition shown below. The servlet mapping may be set as you wish (the URL used must be used by the clients who wish to call the JSON Server and is defined in konakart.properties for clients using the client side of the JSON engine). The default servlet mapping URL is "/konakartjson" but this can be changed if required:


<!-- JSON Server -->
<servlet-mapping>
    <servlet-name>KonaKart_JSON_Servlet</servlet-name>
    <url-pattern>/konakartjson</url-pattern>
</servlet-mapping>

You need to specify the KonaKart engine that the JSON engines will use in the konakart.properties file in the konakart webapp's WEB-INF/classes directory. This section defines the engine class used to service the JSON requests with the default being defined as com.konakart.app.KKEng.


# -----------------------------------------------------------------------------------
# Enterprise Feature
# KonaKart engine class used by the JSON services
# For the default engine use:   com.konakart.app.KKEng
# For the custom engine use:    com.konakart.app.KKCustomEng

konakart.app.json.engine.classname = com.konakart.app.KKEng

# -----------------------------------------------------------------------------------
# Enterprise Feature
# URL for the JSON engine servlet

konakart.json.engine.url = http://localhost:8780/konakart/konakartjson

# Generate match Id on generated JSON Requests

konakart.json.generateMatchIds = false

Note that the property "konakart.json.engine.url" that defines the URL for the JSON service must match the web.xml servlet-mapping defintion (see above).

The property "konakart.json.generateMatchIds" defines whether matching Ids are generated in JSON requests that are sent to the engine. The default for this is false which minimizes message size and parsing time.

As with the POJO, RMI and SOAP versions of the engines, it's easy to select which one you would like to use in your code by simply specifying it by name at runtime.

A very simple example of this is provided in the GetProduct.java example provided in the download kit (under the java_api_examples directory). The example demonstrates how simple it is to select different engines and get the same result with each:


/*
 * Get an instance of the KonaKart engine and retrieve. The method called can be found in
 * BaseApiExample.java
 */
EngineConfig engConf = new EngineConfig();
engConf.setMode(getEngineMode());
engConf.setStoreId(getStoreId());
engConf.setCustomersShared(isCustomersShared());
engConf.setProductsShared(isProductsShared());
engConf.setCategoriesShared(isCategoriesShared());

/*
 * Instantiate a direct java Engine by name - to find a product
 * KKEngIf eng = new KKEng(engConf);
 */
KKEngIf eng = getKKEngByName("com.konakart.app.KKEng", engConf);
System.out.println("Get a product using the KKEng engine");
getProductUsingEngine(eng);

/*
 * Instantiate a java JSON Engine by name - to find a product
 * KKEngIf jsonEng = new KKJSONEng(engConf);
 */
KKEngIf jsonEng = getKKEngByName("com.konakart.json.KKJSONEng", engConf);
System.out.println("Get a product using the KKJSONEng engine");
getProductUsingEngine(jsonEng);

Notice how both of the engines implement the KKEngIf. If you code your solution to the KKEngIf interface you can delay the decision about which engine to use until runtime or (probably more likely) until you have decided how you wish to distribute your KonaKart solution over multiple machines.

The implementation of the getKKEngByName() call used in the above example is provided in the GetProduct.java source file.

Since all four of the application engines implement the same KKEngIf interface the javadoc is applicable to every one of them.

You do not have to use the client side of the JSON engine if you don't want to. Instead you may wish to construct your own client requests yourself. You can derive the format of the requests by applying the standard conventions for translating our KKEngIf into JSON calls as follows.

"f" : Required. The function name, eg. "getProduct".
"s" : Optional. The storeId (required in a multi-store enviornment) eg. "store1".
"i" : Optional. The matchingId (for matching requests with responses - this id is returned in response messages if specified in the request) eg. "1234".
input parameters : Required (they must match the names of the input parameters defined in KKEngIf). Standard JSON format for the input parameters if these are present.
nulls : attributes with null values can be left out of the request. Attributes wih null values are left out of all response messages.

Some examples of JSON requests to the KonaKart JSON Server:


A login request:

{
  "emailAddr" : "fred@flintstone.com",
  "password" : "abcde02",
  "f" : "login",
  "s" : "store1"
}

A customer registration request:

{
  "custReg" : {
    "emailAddr" : "robin@batcave.com",
    "city" : "GothamCity",
    "company" : "ACME Inc",
    "countryId" : 223,
    "faxNumber" : "123456",
    "firstName" : "Robin",
    "gender" : "m",
    "lastName" : "Wayne",
    "newsletter" : "0",
    "postcode" : "st5 ort",
    "productNotifications" : -1,
    "streetAddress" : "12345 Alligator Alley",
    "streetAddress1" : "Blue house",
    "suburb" : "Harlem",
    "telephoneNumber" : "654321",
    "birthDate" : 1303223768362,
    "addressCustom1" : "addressCustom1",
    "addressCustom5" : "addressCustom5",
    "customerCustom1" : "customerCustom1",
    "customerCustom5" : "customerCustom5",
    "groupId" : -1,
    "zoneId" : -1,
    "invisible" : false,
    "state" : "Florida",
    "password" : "abcde02"
  },
  "f" : "registerCustomer",
  "s" : "store1"
}

Some examples of JSON responses from the KonaKart JSON Server:


A response to a login request showing the result which is a sessionId:

{
  "r" : "f663832c049322d2fb6882ba0abf4db9"
}
			
A response from a getCustomer request:
			
{
  "r" : {
    "id" : 123,
    "type" : 0,
    "birthDate" : 1303223708000,
    "emailAddr" : "robin@batcave.com",
    "firstName" : "Robin",
    "gender" : "m",
    "lastName" : "Wayne",
    "telephoneNumber" : "654321",
    "invisible" : 0,
    "numberOfLogons" : 0,
    "defaultAddrId" : 147,
    "globalProdNotifier" : 0,
    "groupId" : -1
  }
}

If an exception is thrown during the processing of a request, the server will respond with a message in JSON format as follows:


An exception thrown in any request where a sessionId is required but cannot
be found is transformed into this JSON response:

{
  "e" : "com.konakart.app.KKException",
  "m" : "The session bad-session-id cannot be found"
}
			
An exception thrown in a login request is transformed into this JSON response:
			
{
  "e" : "com.konakart.app.KKException",
  "m" : "[5] Cannot find customer with email address = bad-user@localhost"
}

An optional JSON Administration server can be enabled to provide programmatic control of the JSON server. (The equivalent is also available on the KKAdmin side). By default this is disabled in the konakart webapp's web.xml. This can be used to enable or disable the JSON server and also to set the included and excluded interfaces to be supported. Note that changes made via the JSON Administration server take effect in real time but are not persisted so the definitions specified in the konakart webapp's web.xml file will take effect on restart of the application.


<!-- Servlet for JSON Admin --> 
<servlet>
<!-- 

    Uncomment the section below if you want to use the JSON Admin Servlet

    When sending these commands the password must match the one defined in the 
    "password" servlet parameter below.

    Only enable the JSON Admin server if you need to and if you do, change the 
    password.

    JSON Admin commands:
        ?cmd=enableJSON&pwd=password
            Enables the JSON server
        ?cmd=disableJSON&pwd=password
            Disables the JSON server
        ?cmd=excludeInterfaces&pwd=password&Interfaces=A,B,C
            Sets the excludedInterfaces to a comma separated list of KKEngIf interfaces
        ?cmd=includeInterfaces&pwd=password&Interfaces=A,B,C
            Sets the includedInterfaces to a comma separated list of KKEngIf interfaces
-->

<!-- JSON Admin
<servlet>
    <servlet-name>KonaKart_JSON_Admin</servlet-name>
    <display-name>KonaKart JSON Admin</display-name>
    <description>KonaKart JSON Admin</description>
    <servlet-class>
        com.konakart.json.KKJSONServerAdmin
    </servlet-class>
    <init-param>
        <param-name>password</param-name>
        <param-value>jason</param-value>
    </init-param>
    <load-on-startup>29</load-on-startup>
</servlet>
End of JSON Admin -->

Prev	Up	Next
Using the RMI APIs	Home	Using the JSON APIs to build a JavaScript client