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:
Calling GeteBayOfficialTime (the Hello World of the Trading API)
Before you execute your first Trading 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/).
To register a test user, see Creating a 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.
This command-prompt command yields a meaningful Perl message if Perl is installed: perl -h
If Perl is not installed:
Add Perl support for SSL and LWP:
ppm
At the ppm>
prompt, enter the following command to download and install Crypt-SSLeay (an SSL package):
install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd
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.
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; }
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. TOKENGoesHERE
with the authentication token that you generated for your test user.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.
As you can see in the sample code, you need to establish the header and request, make the call, and evaluate the response.
# 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.
# 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):
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.
# 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
.
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).
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.
Copyright © 2005–2015 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.