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

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

In this tutorial:

Prerequisites

Calling GetUser (the Hello World of the Trading API)

Understanding the Example

Prerequisites

Before you execute your first Trading API call:

Have a Sandbox test user ready. (Only test users can invoke calls in the Sandbox.)
To register a test user, see Create a test Sandbox user.
Have the authentication token ("auth token") ready for that test user.
Obtain an authentication token for the test user (see Sandbox). 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

install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd

PPM may prompt you to install other modules that are required to support SSL. Accept all additional modules if prompted.
Exit PPM by entering exit.

LWP is a Perl library for the web. If the example below does not work, you may need to download and install LWP from http://cpan.org.

Calling GetUser (the Hello World of the Trading API)

The GetUser call is the simplest call in the Trading API. Call it without specifying the UserID and eBay returns data pertaining to the requesting user (as specified with the eBayAuthToken value). You can use it to verify that the Trading API servers are functioning properly.

Save the following code as MyGetUser.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' => '1207');
$objHeader->push_header('X-EBAY-API-CALL-NAME' => 'GetUser');
$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'?>" .
    "<GetUserRequest  xmlns=\"urn:ebay:apis:eBLBaseComponents\">" .
    "  <RequesterCredentials>" .
    "    <eBayAuthToken>TOKENGoesHERE</eBayAuthToken>" .
    "  </RequesterCredentials>" .
    "</GetUserRequest >";

# 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:

See HTTP Headers for general information about 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 MyGetUser.pl
On success, you'll see an output similar to the following (see Samples in the GetUser reference for more):
```
<?xml version="1.0" encoding="UTF-8"?>
<GetUserResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2025-04-30T11:55:21.190Z</Timestamp>
  <Ack>Success</Ack>
  <Version>1207</Version>
  <Build>E1207_CORE_APISIGNIN_19151597_R1</Build>
  <User>
    <AboutMePage>false</AboutMePage>
    ...
    <EnterpriseSeller>false</EnterpriseSeller>
  </User>
</GetUserResponse>
```
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 time returned for the call was 11:55:21Z.

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' => '1207');
$objHeader->push_header('X-EBAY-API-CALL-NAME' => 'GetUser');
$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-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'?>" .
    "<GetUserRequest xmlns=\"urn:ebay:apis:eBLBaseComponents\">" .
    "  <RequesterCredentials>" .
    "    <eBayAuthToken>TOKENGoesHERE</eBayAuthToken>" .
    "  </RequesterCredentials>" .
    "</GetUserRequest>";

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

GetUser 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 GetUser. 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 GetUser 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"?>
<GetUserResponse 
  xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2025-04-30T11:55:21.190Z</Timestamp>
  <Ack>Failure</Ack>
  <Errors>
    <ShortMessage>Invalid IAF token.</ShortMessage>
    <LongMessage>IAF token supplied is invalid.</LongMessage>
    <ErrorCode>21916984</ErrorCode>
    <SeverityCode>Error</SeverityCode>
    <ErrorClassification>RequestError</ErrorClassification>
  </Errors>
  <Version>1207</Version>
  <Build>E1207_CORE_APISIGNIN_19151597_R1</Build>
</GetUserResponse>

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.