Google+

Follow Us:

Developers Network
Currently Being Moderated

REST Overview: Requests

Introduction

LivePerson provides a simple, open Web interface to its services. The LivePerson APIs conform to the design principles of Representational State Transfer (REST).

Method

This section covers the methods for handling resource requests and the resulting responses.

 

Retrieving a resource:

  • Use an HTTP GET request
  • Specify Query parameters in the form of name/value pairs. For example, you  can add ?skill=Support&maxWaitTime=20,  to add skill and wait time parameters to the request.

 

Updating a resource:

  • Use an HTTP PUT request. Currently PUT requests are supported using a POST  method with the “X-HTTP-Method-Override” header set to the desired method i.e.,  X-HTTP-Method-Override:  PUT.
  • Specify the resource in the request body in the following form:           
    • XML with the Content-Type header set to “application/xml”.
    • JSON with the Content-Type header set to  “application/json”.

 

Creating a resource:

  • Use the HTTP POST request
  • Specify the resource in the request body in the following form:
    • XML with the Content-Type header set to “application/xml”.
    • JSON, with the Content-Type header set to “application/json”.

 

Note: The request URIs as well as all parameter names  are case-sensitive.

 

Version                                              

You must identify the API version number of your application is using. The version number  must be included in every request as a query parameter. Currently use v=1.

Authorization

LivePerson uses unsigned and signed API calls depending on the API.

Unsigned

Using unsigned API calls is useful when creating a first prototype of an application that integrates with LivePerson APIs. By default, accounts are set to not allow unsigned API calls. It is recommended to use signed requests where possible. In some situations, it is not possible to use signed requests (see below).

Authorization Header

An example format of the header for unsigned API calls is as follows:

Authorization: LivePerson appKey={XYZ}


Authorization URL

An example format of the unsigned API calls as URL part is as follows:

?v=1&appKey={XYZ}


where {xyz} is the alphanumeric application key  e.g.,25dfd026beff1bf9913f6148f63a7f81

Signed

Access to the API is restricted to applications which use the OAuth standard to authenticate against the LivePerson platform, and which have been granted explicit access by the account owner. The OAuth protocol requires the account owner to approve each application that makes API calls on their behalf. This approval can be revoked in the future. For more information on OAuth, refer to the OAuth for Signed REST Communication reference document and to http://oauth.net/.

 

Note: Authorization can be set in Headers or URL parameters. Setting authorization in the Headers is the preferred method. Use URL parameters when headers cannot be used.

 

Authorization Header

An example format of the header for signed API calls is as follows:

 

Authorization

OAuth oauth_signature="JA0PvBbTAxmtLmzIWINpSVLshrY%3D", oauth_version="1.0",
oauth_nonce="c1c04ec4-3125-44cf-9c39-cccb9343541b",
oauth_consumer_key="d392e7ff2e204d6c802e38fd775563d1",
oauth_signature_method="HMAC-SHA1",
oauth_token="61adad31204a4e6fab68d560f1ffb594",
oauth_timestamp="1261039670"

 

Note: The Authorization's parameters should be contained on a single line. New lines have been inserted for clarity.

 

Authorization URL

An example format of signed API calls as URL part is as follows:


?v=1&oauth_signature=JA0PvBbTAxmtLmzIWINpSVLshrY%3D

&oauth_version=1.0

&oauth_nonce=c1c04ec4-3125-44cf-9c39-cccb9343541b

&oauth_consumer_key=d392e7ff2e204d6c802e38fd775563d1

&oauth_signature_method=HMAC-SHA1

&oauth_token=61adad31204a4e6fab68d560f1ffb594&
oauth_timestamp=1261039670

 

Why Sign API Requests?

LivePerson account administrators can choose to restrict API access to their account to signed applications only. This is the default setting for all LivePerson accounts. With this setting in effect, an account will only be able to use REST applications that support request signing. By supporting signing, your application will be compatible with all LivePerson accounts, even those with strong security requirements. Request signing ensures that LivePerson can identify the source of each request, and can validate that your application is being used with the account owner’s express knowledge and consent. In addition, it allows the account owner to grant access to the account’s data and services without the exchange of sensitive login information such as user names and passwords, and to revoke this access at any time.

When should Applications Sign Requests?

Request signing can be used both by server-based applications, as well as applications deployed to the desktop or a device, so long as a compatible OAuth library is available on the target platform. For situations where direct OAuth signing is not possible, or for situations where there is concern that key secrets will be public (for example, a script library) it is best to take a proxy approach and pass requests through a server-side application which can perform the signing.

  • Key secrets and Access Token secrets should be treated as sensitive data which should not be widely distributed.
  • It is acceptable to embed an application key secret in the code of a desktop or other installed application. However, access token secrets should generally be stored on backend servers, or stored locally by a desktop/mobile application after it has been installed by an authorized account administrator (this process is verified by the exchange of the verification code during installation or configuration).

 

Output Format

You can change the format  extension of a request to obtain results in the format of your choice. The  documentation indicates which formats are available for each method. The API  currently supports the following data formats: XML and JSON with some methods  only accepting a subset of these formats.

 

All requests have the  option of specifying an Accept header in the request to indicate the desired  formats of the response. As an alternative to the Accept header, you can use an  extension-like form of the URL to receive the desired response format.

 

For example you can  use:

POST  http://sales.liveperson.net/api/account/12345678/chat/request.xml

Instead of:

POST http://sales.liveperson.net/api/account/12345678/chat/request

Accept: application/xml

 

Notes:

  • The “extension” is case-sensitive, that is, /request.XML will not work.
  • If both the Accept header and an extension are provided, the extension  takes precedence over the Accept  header.

 

Supported Formats

  • XML
  • JSON

 

Encoding

Special characters in URLs such as spaces, percent signs and non ASCII characters should be encoded as octets according to UTF-8 and then percent encoded. URLs should be encoded according to RFC 3986 section  2.5:

 

Note: Two special characters in XML elemental data are '&' and  '<'. When using a POST request that requires an XML body, these characters need to be escaped (&amp; and&lt; respectively) in order for the XML to  be accepted.

Comments

Delete Document

Are you sure you want to delete this document?