Transactions

An API session requires that a session first be established, then subsequent transactions be conducted using a unique set of identifiers. This section details how to establish a session and conduct transactions.

Requests and inputs

1010data API transactions are conducted using the HTTPS POST method. A transaction request consists of a POST URL and a POST body. The POST URL contains the gateway information along with the current session ID, encrypted password, API transaction name, and various other pieces of information. Most transactions require an XML input file and return an XML data structure.

The following is an example of an HTTPS query string that would be provided as the POST URL:
https://www2.1010data.com/gw.k?api=query&apiversion=3&uid=$UID&pswd=$PSWD&sid=$SID
Note: The user ID, encrypted password, and session ID are represented by the variables $UID, $PSWD and $SID respectively.

Each transaction has its own XML input specification, which is detailed in the reference documentation of the transaction. An example of an XML input for the query transaction is shown below:

POST /cgi-bin/gw.k?api=query&apiversion=3&uid=$UID&pswd=$PSWD&sid=$SID https/1.1
Content-Type: text/xml
Content-Length: 133
<in>
 <name>pub.doc.retail.salesdetail</name>
 <ops>
  <sel value="i_<10"/>
  <colord cols="trans_date,store,xsales"/>
 </ops>
</in>
The example above provides a full POST header containing the following pieces of information according to the HTTPS 1.1 POST protocol:
POST
The HTTP method being called.
URL
The POST URL is appended to https://www2.1010data.com and contains numerous pieces of information important to the transaction being conducted. The data required for the query string is provided in detail in the documentation for each transaction. A brief description of each is shown below:
cgi-bin/gw.k
This piece of the query string specifies the gateway used for the transaction. This information is required for each transaction, but is also the same for each transaction.
?
Indicates a query consisting of key/value pairs will follow.
api=$TRANSACTION_NAME
Specifies the name of the transaction to be conducted. The transaction named specifies the input required for the transaction and the information that will be returned by the system.
uid=$UID
Specifies the 1010data user ID under which transactions will be conducted.
pswd=$PSWD
The password or encrypted password used to authenticate a session and conduct transactions. The login transaction requires the user's unencrypted password. All other transactions, which can only be conducted during an active session, require the encrypted password returned by the login transaction.
sid=$SID
The session ID for the current session. The session ID is returned by the login transaction and is required for conducting subsequent transaction. Once a session ends the SID is no longer valid.
https 1.1
Specifies the version of the http/https protocol being used for the transaction. The 1010data XML API is compliant with http 1.0, http 1.1, https 1.0, and https 1.1.
Content-Type: text/xml
Specifies the type of data being sent in the POST body. The 1010data XML API is always of Content-Type text/xml.
Content-Length
Specifies the number of bytes in the POST body.
XML Input
The XML input is dependent on the transaction being called and must be placed in the POST body. If no input is required for the transaction the body may be left empty.

Response from 1010data

The response from the server is also in the form of a header followed by XML contents. An example of such a message is as follows:
HTTP/1.1 200 OK
Date: Sun, 23 Dec 2001 04:27:43 GMT
Server: Apache/1.3.9 (OpenSA) (Win32) mod_ssl/2.4.2 OpenSSL/0.9.4
Content-Length: 612
Connection: close
Content-Type: text/xml
<out>
    <rc>0</rc>
    <msg>query successful</msg>
    <nrows>365</nrows>
    <table>
        <cols>
            <th name="date" type="i" format="type:date">
                Date
            </th>
            <th name="t0" type="f" format="type:num;width:6;dec:2">
                Average
                Dry Bulb
                Temp
                (Celsius)
            </th>
            <th name="t1" type="f" format="type:num;width:6;dec:2">
                Average
                Relative
                Humidity
                (%)
            </th>
        </cols>
        <data/>
    </table>
</out>

The information in the contents depends on the type of transaction, but it always includes the following two elements:

<rc> return code (0 means OK, 1-39 means error) </rc>
<msg> message </msg>

The error codes are described in detail in the next section.