Perl: XML API: Making Your First Call (GeteBayOfficialTime)

This tutorial illustrates the basics of executing a call in the eBay Trading APIs (Trading API) via Perl — specifically, the GeteBayOfficialTime call.

In this tutorial:

Prerequisites

Calling GeteBayOfficialTime (the Hello World of the Trading API)

Understanding the Example

Prerequisites

Before you execute your first Trading API call:

Have your Sandbox Keys available, as you will need them in order to make the API call.
Your Sandbox Keys are the three IDs (DevID, AppID, and CertID) you generated after you joined the eBay Developers Program (see Using the Sandbox for information on how to generate these keys). If you are not the primary contact for your program membership, you may need to get these keys from the person who originally signed up. If you are the primary contact and you cannot find your keys, please fill out a Request for Session Certificate Information on the Developer Zone site (http://dev.developer.ebay.com/contactus/).
Have a Sandbox test user ready. (Only test users can invoke calls in the Sandbox.)
To register a test user, see Creating a Test User.
Have the authentication token ("auth token") ready for that test user.
Obtain an authentication token for the test user (see Generating Auth Tokens for Sandbox Test Users). You must have a token in order to make any calls to the Trading API.
Ensure Perl is installed, with support for SSL and LWP.
This command-prompt command yields a meaningful Perl message if Perl is installed: perl -h

If Perl is not installed:
- If you are using Windows, download and install Perl from ActiveState:
  http://www.activestate.com/activeperl
- If you are using a UNIX-based system, Perl is probably already included on your machine. If it is not, see http://www.perl.org
Add Perl support for SSL and LWP:
1. Start the Perl Package Manager from the command line by entering ppm
2. PPM may prompt you to install other modules that are required to support SSL. Accept all additional modules if prompted.
3. Exit PPM by entering exit.

Calling GeteBayOfficialTime (the Hello World of the Trading API)

The GeteBayOfficialTime call is the simplest call in the Trading API. You call it and it returns the time according to eBay. You can use it to synchronize the time in your system with eBay official time, and you can use it to verify that the Trading API servers are functioning properly.

Save the following code as MyGetTime.pl

use strict;
use LWP::UserAgent;
use HTTP::Request;
use HTTP::Headers;

# define the HTTP header
my $objHeader = HTTP::Headers->new;
$objHeader->push_header('X-EBAY-API-COMPATIBILITY-LEVEL' => '391');
$objHeader->push_header('X-EBAY-API-DEV-NAME' => 'yourdevname');
$objHeader->push_header('X-EBAY-API-APP-NAME' => 'yourappname');
$objHeader->push_header('X-EBAY-API-CERT-NAME' => 'yourcertname');
$objHeader->push_header('X-EBAY-API-CALL-NAME' => 'GeteBayOfficialTime');
$objHeader->push_header('X-EBAY-API-SITEID' => '0');
$objHeader->push_header('Content-Type' => 'text/xml');

# define the XML request
my $request =
    "<?xml version='1.0' encoding='utf-8'?>" .
    "<GeteBayOfficialTimeRequest xmlns=\"urn:ebay:apis:eBLBaseComponents\">" .
    "  <RequesterCredentials>" .
    "    <eBayAuthToken>TOKENGoesHERE</eBayAuthToken>" .
    "  </RequesterCredentials>" .
    "</GeteBayOfficialTimeRequest>";

# make the call
my $objRequest = HTTP::Request->new(
  "POST",
  "https://api.sandbox.ebay.com/ws/api.dll",
  $objHeader,
  $request
);

# deal with the response
my $objUserAgent = LWP::UserAgent->new;
my $objResponse = $objUserAgent->request($objRequest);
if (!$objResponse->is_error) {
  print $objResponse->content;
}
else {
  print $objResponse->error_as_HTML;
}

Modify the code to use your identifying information:

Change all occurrences of yourdevname, yourappname, and yourcertname with your Sandbox Developer ID, Application ID, and Certificate ID, respectively. See Routing the Request (Gateway URLs) for general information about these HTTP headers.
Replace TOKENGoesHERE with the authentication token that you generated for your test user.

At a command prompt, change to the directory of your new Perl script and type perl MyGetTime.pl

On success, you see output similar to this:

<?xml version="1.0" encoding="UTF-8"?>
<GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2005-01-13T21:47:01.407Z</Timestamp>
  <Ack>Success</Ack>
  <CorrelationID>00000000-00000000-00000000-00000000-00000000-00000000-0000000000
  </CorrelationID>
  <Version>393</Version>
  <Build>20050110220901</Build>
</GeteBayOfficialTimeResponse>

The eBay time is found in the Timestamp element, and the Ack (acknowledgement) element indicates that the call succeeded. This particular response indicates that at the time the call was made, the eBay official time was 21:47:01 GMT.

Understanding the Example

As you can see in the sample code, you need to establish the header and request, make the call, and evaluate the response.

Defining the Header

# define the HTTP header
my $objHeader = HTTP::Headers->new;
$objHeader->push_header('X-EBAY-API-COMPATIBILITY-LEVEL' => '391');
$objHeader->push_header('X-EBAY-API-DEV-NAME' => 'yourdevname');
$objHeader->push_header('X-EBAY-API-APP-NAME' => 'yourappname');
$objHeader->push_header('X-EBAY-API-CERT-NAME' => 'yourcertname');
$objHeader->push_header('X-EBAY-API-CALL-NAME' => 'GeteBayOfficialTime');
$objHeader->push_header('X-EBAY-API-SITEID' => '0');
$objHeader->push_header('Content-Type' => 'text/xml');

Each call to the Trading API involves an HTTP header portion and an XML portion.

New versions of the Trading API are released on a regular basis, and certain versions are designated as compatibility levels. The set of required inputs fields or output fields that are returned for a call may differ for each compatibility level, which can help decrease the burden on users of the Trading API to keep updating applications with each and every release of the Trading API. X-EBAY-API-COMPATIBILITY-LEVEL establishes the Trading API compatibility level of the call.

X-EBAY-API-DEV-NAME, X-EBAY-API-APP-NAME and X-EBAY-API-CERT-NAME specify the user's eBay Developer Program Sandbox Keys. These allow eBay to identify what application is making the call.

X-EBAY-API-CALL-NAME identifies which call.

X-EBAY-API-SITEID specifies which site you are making the call to. Any input data you send will go to the site you specify, and any data returned will be data from that site.

Content-Type should always be set to text/xml for the Trading API since the information is submitted in XML form.

Defining the Request

# define the XML request
my $request =
    "<?xml version='1.0' encoding='utf-8'?>" .
    "<GeteBayOfficialTimeRequest xmlns=\"urn:ebay:apis:eBLBaseComponents\">" .
    "  <RequesterCredentials>" .
    "    <eBayAuthToken>TOKENGoesHERE</eBayAuthToken>" .
    "  </RequesterCredentials>" .
    "</GeteBayOfficialTimeRequest>";

To learn what are the valid input elements for a call, see the API Reference for the particular call. In the case of GeteBayOfficialTime, there are no input elements other than the "Standard Input Fields" (fields common to all calls, though not all calls use every one of the fields):

GeteBayOfficialTime reference

The XML document submitted to the Trading API is a string, here assigned to $request. The name of the root element for the input XML of a call is always name of the call with the word Request appended to it. In this case, the root element is GeteBayOfficialTimeRequest. The namespace for the request is declared in the xmlns attribute on the root element. Each call to the Trading API must specify the urn:ebay:apis:eBLBaseComponents namespace.

The authentication token is contained in the eBayAuthToken element. This authenticates the eBay user on whose behalf the call is being made by the application.

No other information needs to be specified in the request for the GeteBayOfficialTime call, whereas for most other calls, additional XML tags are required or allowed.

Making the Call

# make the call
my $objRequest = HTTP::Request->new(
  "POST",
  "https://api.sandbox.ebay.com/ws/api.dll",
  $objHeader,
  $request
);

The HTTP::Request object specifies the HTTP POST method, the URL to which to send the request (the Sandbox URL for Trading API calls), the HTTP header ($objHeader) and HTTP request ($request). Note that HTTP method names are case sensitive (e.g., "POST").

The $objUserAgent object submits the request and the response is assigned to $objResponse.

Dealing with the Response

my $objUserAgent = LWP::UserAgent->new;
my $objResponse = $objUserAgent->request($objRequest);
if (!$objResponse->is_error) {
  print $objResponse->content;
}
else {
  print $objResponse->error_as_HTML;
}

The "if" block examines $objResponse. If it is not an error, the script prints the content of the response.

The content of the response is the XML document returned by the call. To isolate just the time, you would need to parse this content (e.g. use XPath expressions or regular expressions).

Dealing with Errors

If there are errors as a result of making a call (other than syntax errors in your own Perl coding), the Ack element will contain the word Failure, and details about the error can be found in the Errors element (with Short and LongMessage elements elaborating on the problem.

For example, this is the error that is returned when you provide an incorrect authentication token:

<?xml version="1.0" encoding="UTF-8"?>
<GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Ack>Failure</Ack>
  <Errors>
    <ShortMessage>Auth token is invalid.</ShortMessage>
    <LongMessage>Validation of the authentication token in API request failed.</LongMessage>
    <Error Code>931</ErrorCode>
    <SeverityCode>Error</SeverityCode>
  </Errors>
  <Version>393</Version>
  <Build>20050110220901</Build>
</GeteBayOfficialTimeResponse>

If the call has errors, the code prints those errors to the string. Again, a real application could parse the XML to determine the cause of the error, and either display it or else take some action to attempt to recover from the error gracefully.