HTTP Example

An example HTTP request response pair shows how HTTP is used in the Product Import operation, described in in the next section.

Note that in this example, the XML is passed in the body of the HTTP POST. In other POST operations, such as the Order Cancellation operation, the body will consist of request parameters as URL encoded name value pairs.

Request

POST /rtd2-host/remoteorder/imports/importitems.xml HTTP/1.1
channel: MYCHANNEL
user: philz
password: cGhpbHo=
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 127.0.0.1:8080
Content-Length: 967

<?xml version="1.0" encoding="UTF8"?>
<imports>
  <import type="product" operation="insert" externalReference="TEST_fullproduct">
    externalReference=TEST_fullproduct
    description=A description for the test product
    weight=100
    weightUnits=grams
    type=default
    quantityOnOrder=10
    imageReference=TEST_fullproduct.gif
    priceNet=10.50
    priceGross=11.50
    tax=1.50
    taxCode=T1
    currency=GBP
    currencyUnits=pounds
    userDefined1=User defined field value 1
    userDefined2=
    userDefined3=
    userDefined4=
    userDefined5=
    channel=MYCHANNEL
    type=default
    activated=true
  </import>
  <import type="product" operation="insert" externalReference="TEST_min_product">
    description=A description for the min product
    organisation=altco
    type=default
    activated=true
  </import>
  <import type="product" operation="insert" externalReference="TEST_global_product">
    externalReference=TEST_global_product
    description=A description for the global product
    type=default
    activated=true
  </import>
</imports>

Note how the channel external reference is passed in using the channel header.

In the example above the user name and password (in this case philz) are passed as headers, with the password being Base64 encoded. The other authentication method uses HTTP Basic Authentication (as described on Wikipedia). In this case, the user name and password headers would be replaced by the following:

Authorization: Basic cGhpbHo6cGhpbHo=

where cGhpbHo6cGhpbHo= is the base Base64 encoding of philz:philz.

Below we show both the normal and the error response to a this request.

Response

Normal Response

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(6.1.14)

<?xml version="1.0" encoding="UTF-8"?>
<importResult>
  <importSuccesses>
    <import type="product" operation="insert" externalReference="TEST_fullproduct"
      entity="rtd.domain.database.Product" item="TEST_fullproduct"
      queryTime="2014-09-28 20:32:34.620" />
    <import type="product" operation="insert" externalReference="TEST_min_product"
      entity="rtd.domain.database.Product" item="TEST_min_product"
      queryTime="2014-09-28 20:32:34.636" />
    <import type="product" operation="insert" externalReference="TEST_global_product"
      entity="rtd.domain.database.Product" item="TEST_global_product"
      queryTime="2014-09-28 20:32:34.658" />
  </importSuccesses>
  <importFailures></importFailures>
</importResult>

Notice how the result is returned in the body of the HTTP request, normally in XML format.

Error Response

HTTP/1.1 500 Internal Server Error
Content-Language: en-US
Content-Type: text/xml; charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(6.1.14)

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <message>
     <![CDATA[Cannot authenticate &apos;MYCHANNEL&apos;. 
        Does not match list of authenticated channel]]></message>
  <detail>
       <![CDATA[Cannot authenticate &apos;MYCHANNEL&apos;. 
        Does not match list of authenticated channel(rtd ...]]>
  </detail>
</message>
</error>

For most of the operations, an error which prevents successful completion of the operation results in a HTTP response with a non-200 response code. In this case, more details can be extracted from the message and detail elements.

Error Responses

When an error occurs in one of the XML operations, OrderFlow will respond in a standard way. Typically, it will return a non 200 HTTP return code. For example, if the user is not authenticated then a 401 return code will be returned. If the server is unable to complete the request due to some other application error, a 500 return code will be returned.

OrderFlow will return error text in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <message>high level error message</message>
  <detail>stack trace of error message</detail>
</error>

Error text is generated dynamically, with the intention being to return meaningful text that will help diagnose and correct problems. This approach means that it is not possible to provide an exhaustive list of errors that may be returned by the API.

Examples of the most common errors found in the element of are API response are given below.

HTTP Code	Error Text	Explanation
HTTP 500 Internal Server Error	Unable to load XML document from resource	The message structure or XML content cannot be parsed, check the XML formatting.
HTTP 500 Internal Server Error	Expecting value for 'channel' request header or parameter	The channel value was not found in the HTTP request header
HTTP 500 Internal Server Error	Cannot authenticate 'channelexample' Does not match list of authenticated channel	The channel contained in the HTTP request header is not valid
HTTP 412 Precondition failed	No user for supplied user name and password combination	Username / password combination is invalid
HTTP 200	Duplicate entity in import of order with reference: 03340002 Rejected instance rtd.domain.database.OrderItem with reference '03340002'.	The order '03340002' already exists for the channel
HTTP 200	No product found for external reference: WRONGPRODUCT. If this product is present, make sure that it has been activated.	A product code contained within the order is unrecognized
HTTP 200	Failed to convert property value of type 'java.lang.String' to required type 'java.lang.Double' for property 'totalPriceGross' nested exception is java.lang.NumberFormatException For input string: '19t6.99'	The value 'totalPriceGross' could not be stored as a numeric value
HTTP 200	Unable to find any entity associated with identifier:ref:courier:worldship	The courier identifier “worldship” does not exist or is inactive