Concept - JavaScript REST Client

Introduction

ISHRestClient is a JavaScript based class to handle REST calls. It allows to execute any REST call and provide useful utility methods to prepare a JSON REST response.

Glossary

ISHRestClient - Intershop REST Client

Configuration

To configure the ISHRestClient utilize the following methods:

client.host('/INTERSHOP/rest/WFS');
- Set the Intershop host part of the REST url in the Intershop REST client.
client.prefix('inSPIRED-inTRONICS_Business-Site/-');
- Set the REST prefix part of the REST URL with the Domain and URLIdentifier in the Intershop REST client.
client.token('demo@PLAIN:lcmI551YIjY=|VDcwS0RnQVZJcXNBQUFGV0Y0R3owQWM0QDE0NjkxODA0NTQ2NDU=');
- Set the authentication token for the REST request in the Intershop REST client.
client.auth('Basic xxxxxxxxx=');
- Set the basic authentication for the REST request in the Intershop REST client.
  The basic authentication is only needed when the authentication token is not available.
client.customer('customers/AgroNet/users/fbirdo@test.intershop.de');
- Set the URL part with the related customer for whom the request is called.
- Examples for B2C and B2B:
  - B2C: customers/Patricia
  - B2B: customers/AgroNet/users/fbirdo@test.intershop.de

Automatic REST Client Configuration

If there is a RESTConfiguration instance available the ISHRestClient implementation sets the related configuration values automatically.

More information on the RESTConfiguration:

Methods

The precondition to use the class is to create an instance of the REST client.

Example

var client = new ISHRestClient();

host

host( <url> )

Setter and Getter for REST call host URL.

Description:

Set the Intershop host part of the REST URL in the Intershop REST client.
The method is chainable.

Parameter List:

url (string) optional
String with part of the REST URL.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set value.

Example

var client = new ISHRestClient();
client.host('/INTERSHOP/rest/WFS'); // Setter
client.host(); // Getter

prefix

prefix( <url> )

Setter and Getter for REST call prefix URL.

Description:

Set the rest prefix part of the REST URL with the Domain and URLIdentifier in the Intershop REST client.
The method is chainable.

Parameter List:

url (string) optional
String with part of the REST URL.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set value.

Example

var client = new ISHRestClient();
client.prefix('inSPIRED-inTRONICS_Business-Site/-'); // Setter
client.prefix(); // Getter

header

header( <map> )

Setter and Getter for REST call header data.

Description:

Set all defined header data for the REST request in the Intershop REST client.
The method is chainable.

Parameter List:

map (json object) optional
Object with all header data in a key value map.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set header options.

Example

var client = new ISHRestClient();
client.header({
    "Accept": "application/json",
    ...
}); // Setter
client.header(); // Getter

data

data( <map> )

Setter and Getter for REST call request data.

Description:

Set the rest prefix part of the REST URL with the Domain and URLIdentifier in the Intershop REST client.
The method is chainable.

Parameter List:

map (json object) optional
Object with all request data in a key value map.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set request data map.

Example

var client = new ISHRestClient();
client.data({
    "param1": "...",
    "param2": "...",
    ...
}); // Setter
client.data(); // Getter

uri

uri()

Getter for full REST request URL.

Description:

Get the full REST request URI with base URI and also the complete resource path.

Parameter List:

none

Returns

Returns the URI as a string.
(Will used internal in the REST client class)

Example

var client = new ISHRestClient();
client.uri();

auth

auth( <auth> )

Setter and Getter for REST call basic authorization.

Description:

Set the basic authorization (e.g., 'Basic xxxxxxxxx=') for the REST call.

Parameter List:

auth (string)
String with the basic authorization.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set basic authorization string.

Example

var client = new ISHRestClient();
client.auth('Basic xxxxxxxxx='); // Setter
client.auth(); // Getter

token

token( <token> )

Setter and Getter for REST call authentication token.

Description:

Set the authentication token (e.g., 'demo@PLAIN:lcmI551YIjY=|xxxxxxxxxxxxx=') for the REST call.

Parameter List:

token (string)
String with the authentication token.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set authentication token string.

Example

var client = new ISHRestClient();
client.token('demo@PLAIN:lcmI551YIjY=|VDcwS0RnQVZJcXNBQUFGV0Y0R3owQWM0QDE0NjkxODA0NTQ2NDU='); // Setter
client.token(); // Getter

error

error( <statusCode>, <handler> )

Setter and Getter for REST call error handler functions.

Description:

Parameter List:

errorCode (int)
Integer with the status code.
handler (function)
Defined the handler function that is called by related response error with the defined error code.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns a collection ( Array ) of all registered error handler.

Example

var client = new ISHRestClient();
client.error('401', function(jqXHR, textStatus, errorThrown) {
     // ... customized code
});
client.error(); // Getter

customer

customer( <urlPart> )

Setter and Getter for REST call customer url part.

Description:

Set the URL part with the related customer for whom the request is called.
The method is chainable.

Parameter List:

urlPart (string) optional
String with part of the REST request URL.

Returns

Using as setter method
- Returns the set current instance of the REST client itself. So the method is chainable.
Using as getter method
- Returns the set value.

Example

var client = new ISHRestClient();
client.customer('customers/AgroNet/users/fbirdo@test.intershop.de'); // Setter for B2B
client.customer('customers/Patricia'); // Setter for B2C
client.customer(); // Getter

create

create( <resource>, <requestData> )

Calls a request with method 'POST'.

Description:

Calls a Ajax request with method 'POST' with all set options and headers.
The method is chainable.

Parameter List:

resource (string)
String with the called REST resource.
requestData (json object) optional
JSON with all request data that be sent in a key value map.
(To set these data the internal method data() will be used)

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Example

var client = new ISHRestClient();
client.create('/recurringorders', {
	"param1": "...",
	...
}).then(function(data) {
	// ... custom code with response data
});

get

get( <resource> )

Calls a request with method 'GET'.

Description:

Calls a Ajax request with method 'GET' with all set options and headers.
The method is chainable.

Parameter List:

resource (string)
String with the called REST resource.

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Example

var client = new ISHRestClient();
client.get('/recurringorders').then(function(data) {
	// ... custom code with response data
});

update

update( <resource>, <requestData> )

Calls a request with method 'PUT'.

Description:

Calls a Ajax request with method 'PUT' with all set options and headers.
The method is chainable.

Parameter List:

resource (string)
String with the called REST resource.
requestData (json object) optional
JSON with all request data that be sent in a key value map.
(To set these data the internal method data() will be used)

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Example

var client = new ISHRestClient();
client.update('/recurringorders', {
	"param1": "...",
	...
}).then(function(data) {
	// ... custom code with response data
});

delete

delete( <resource> )

Calls a request with method 'DELETE'.

Description:

Calls a Ajax request with method 'DELETE' with all set options and headers.
The method is chainable.

Parameter List:

resource (string)
String with the called REST resource.

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Example

var client = new ISHRestClient();
client.del('/recurringorders/123456789').then(function(data) {
	// ... custom code with response data
});

getElements

getElements()

Calls a request with method 'DELETE'.

Description:

Resolve all links in the response and calls separate get requests for each links.
The result is a collection with the response of each link requests.
The method is chainable.

Parameter List:

resource (string)
String with the called REST resource.

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Example

var client = new ISHRestClient();
client.getElements('/recurringorders').then(function(data) {
	// ... custom code with all response data of all each link requests
});

Example for a typical link list response

{
  "elements": [
    {
      "type": "Link",
      "uri": "inSPIRED-inTRONICS_Business-Site/-/customers/AgroNet/users/fbirdo@test.intershop.de/quoterequests/OmwKDgAhF5IAAAFTgy8bsDHK",
      "title": "OmwKDgAhF5IAAAFTgy8bsDHK"
    },
    {
      "type": "Link",
      "uri": "inSPIRED-inTRONICS_Business-Site/-/customers/AgroNet/users/fbirdo@test.intershop.de/quoterequests/brcKDgAhwXEAAAFTti0bsDHO",
      "title": "brcKDgAhwXEAAAFTti0bsDHO"
    }
  ],
  "type": "ResourceCollection",
  "name": "quoteRequests"
}

getReducedAttrCollection

getReducedAttrCollection( <attributes> )

Get an optimized collection of all given response attributes.

Description:

The method converts the data structure of all given attributes from the response to an simple collection with all attributes in a key value map.
The method is chainable.

Parameter List:

attributes (array)
Array with all given response attributes in form of the following

Example for attributes in a response

{
    "elements":[
        {
            "type":"Link",
            "attributes":[
                {
                    "name":"number",
                    "type":"String",
                    "value":"0000009"
                },
                {
                    "name":"creationDate",
                    "type":"Long",
                    "value":1469533578641
                },
                {
                    "name":"startDate",
                    "type":"Long",
                    "value":1469533578641
                },
                {
                    "name":"endDate",
                    "type":"Long",
                    "value":1469533578641
                },
                {
                    "name":"interval",
                    "type":"Period",
                    "value":"P3M"
                },
                {
                    "name":"active",
                    "type":"Boolean",
                    "value":false
                },
                {
                    "name":"itemCount",
                    "type":"Integer",
                    "value":3
                },
                {
                    "name":"total",
                    "type":"MoneyRO",
                    "value":{
                        "type":"Money",
                        "value":430.37,
                        "currencyMnemonic":"USD"
                    }
                },
                {
                    "name":"lastOrderDate",
                    "type":"Long",
                    "value":1469533578641
                },
                {
                    "name":"buyer",
                    "type":"String",
                    "value":"Fritz Birdo"
                }
            ],
            "uri":"inSPIRED-inTRONICS_Business-Site/smb-responsive/customers/AgroNet/users/fbirdo@test.intershop.de/recurringorders/recurringOrderID9",
            "title":"recurringOrderID9"
        }
	]
}

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Example of a reduced attributes array

{
  "elements": [
    {
      "attributes": [
        {
          "active": true,
          "buyer": "Fritz Birdo",
          "creationDate": 1469533578641,
          "endDate": 1469533578641,
          "interval": "P14D",
          "itemCount": 14,
          "lastOrderDate": 1469533578641,
          "number": "0000010",
          "startDate": 1469533578641
        },
        {
          "active": false,
          "buyer": "Fritz Birdo",
          "creationDate": 1469533578641,
          "endDate": 1469533578641,
          "interval": "P2W",
          "itemCount": 7,
          "lastOrderDate": 1469533578641,
          "number": "0000021",
          "startDate": 1469533578641
        }
      }
    }
  ]
}

Example

var client = new ISHRestClient();
client.get('/recurringorders').then(function(data) {
	var model = client.getReducedAttrCollection(data.elements);
});

__call

__call()

(PRIVATE) - Triggers the calling of the REST call by jQuery.ajax()

Description:

Calls the jQuery Ajax request with all configurations.
This method will only be called internal (private) and will be called from the methods create, update, get or delete.
The method is chainable.

Parameter List:

none

Returns

Returns the response as a jQuery.ajax() promise object.
So it is possible to use the chainable method then() after the REST request.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Table of Contents

Introduction

Glossary

Configuration

Methods

host

prefix

header

data

uri

auth

token

error

customer

create

get

update

delete

getElements

getReducedAttrCollection

__call