Home ⋮ Knowledge Base
Concept - JavaScript REST Client
Share this document

Table of Contents


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:

Register a handler function for a specific Ajax error code.

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.