Welcome To Our Customer Service Portal


Nanorep widget protocol API

 

 

Abstract

This document presents the API used to communicate with the Nanorep service.

For more information and answers, please consult our Nanorep on our website.

 

Introduction

The Nanorep API is an XML over HTTP protocol, based on a request-response paradigm.

All requests are sent to http://my.Nanorep.com/KB, with a POST http request method.

For each request, you will need a session Id, which is obtained via a Login request.

 

After using a login-request to obtain a session-id, the API can be used to search, open tickets, request Analytics and statistics information, and more.

 

The following sections of the document will walk you through sending and receiving the various types of requests supported by the API.

 

For more information and answers, please consult our Nanorep on our website.

 


Note: All implementation of the Nanorep API requires the placement of the Nanorep logo, or the text 'powered by Nanorep' in a clear location next to the user UI, unless specifically authorized in writing by Nanorep.

 


 

 

Logging in – Creating a Session

The Login-Request provides you with a new unique session-id which is required for sending queries to the system. Any attempt to use an invalid session-id will result in a 400 BAD REQUEST response from the server, which is common with session expiration occurring after an idle timeout, so implementers should be prepared to handle these errors and send a new Login-Request before resuming sending queries.

 

 

Login Request syntax

<Nanorep>

   <Login anonymous='true'>

<WidgetAPI version="1.22" account="account" enableStats="enableStats">

                            <pageUrl><![CDATA[referringPage]]></pageUrl>

                </WidgetAPI>

   </Login>

</Nanorep>

 

account

Nanorep Account name.

enableStats

accepts 'true' or 'false', enables analytics tracking for this session.

referringPage

the URL of the page from which the API is used.

 

After sending a Login-Request, the service will reply with a Login-Response, which will contain information regarding the generated session (if succeeded), or error information (if failed)

Here is the login response syntax:               

 

Login Response syntax

<Nanorep>

   <LoginResponse sessionId='sessionId' initCode='0' lang='en'          timeout='sessionIdleTimeout'> message </LoginResponse>

</Nanorep>

 

 

sessionId

if non-zero, login is successful. Otherwise, Message will contain info regarding the failure.

sessionIdleTimeout 

Specifies the maximum time in seconds a session can stay idle before it is expired on the service. When a session is expired you will be required to send a new login request to obtain a new session-id.

 


Note: Using an expired session-id will result in an error code 400 response,after which you can send a new login-request

If you receive error code 400 for the login request, your login request was illegal, check your account name, and referring page configuration.


 

 After a successful login, you may use the provided sessionId to send queries to the service.

Query Request Structure

All Nanorep API requests share a common structure, containing an XML envelope, and a<Session> tag with some common parameters

Protocol Request structure

<?xml version='1.0' encoding='UTF-8' ?>

<Nanorep>

                 <Session id='sessionId' userUniqueId='0' requestId=''requestId'/>

                ...

</Nanorep>

 

sessionId

The Session id you received in the login response.

requestId

A unique id (for this session only) used by the service, normally this id starts at a fixed number (i.e 1, although it can start at any number) and is incremented for each subsequent request.

request id should never be repeated, and is used by the service to uniquely identify requests, in cases of network errors and re-transmissions.

 

 

 

In addition to the <Session> tag, the XML envelope will contain the additional query syntax.

 

for example, a valid Search-Query request will look as follows:

Query request example

POST /KB HTTP/1.1

Host: my.Nanorep.com

Connection: keep-alive