Overview

eBay provides a very large set of web service API’s for developers to interact with.  It can be somewhat daunting to developers at any level and especially to developers without much experience dealing with web services.

PHP is a little bit unique among programming languages in that it can be used in a very “loose” fashion with basic scripting techniques or it can be very structured and require more skill to accomplish certain tasks if you’re using a framework such as CakePHP, CodeIgniter or the Zend Framework, for example.

Much of the time, documentation and SDK’s provided for eBay’s web services are geared more towards intermediate to advanced level PHP developers that are using these frameworks and focus on SOAP tools to accomplish tasks within the eBay system.  This tends to be confusing for developers that aren’t quite at this level yet, and it can make it very difficult to accomplish a simple task because one finds themselves buried in documentation and moving in the wrong direction while attempting to accomplish a goal for themselves or for a client.

While I do recommend learning how to follow standards within the PHP language and using frameworks to aid in development, that’s not always an immediate option for developers.  As such, I’d like to spend a little bit of time in this article covering a simple method for working with eBay API’s that any PHP developer can use within any project even if you’re a PHP rookie.

This will be a 2-part article.  In this first part, I will cover all of the basics of exactly what is involved to accomplish our goal.  Then, in part 2, we’ll get our hands dirty and use these techniques to build some requests and parse the response from scratch.

Steps for Making Calls with the eBay API

In order to communicate with eBay’s web services there are just a few simple steps we need to follow.  I’ll list them here just so you can get an idea of exactly what’s involved in order to quickly erase any thoughts you might have that this will be too complicated for you.  Then we’ll take a closer look at exactly how to accomplish each of these steps.  Part 2 of this series will then cover in detail exactly how to build the requests and handle the response accordingly.

1. Prepare API credentials and ensure they’re available to the application.
2. Generate a request that we’ll send to eBay’s web service.  This includes two separate tasks.
   1. Generate HTTP request headers.
   2. Generate XML formatted request string.
3. Send the request to eBay using the CURL functions included with PHP.
4. Parse the XML response returned from eBay in order to pull out the necessary data and make it available to our application.

That’s essentially it, folks.  There’s really not a whole lot to it when you look at it that way.  Now let’s take a closer look at each one of these steps.

Step 1 – Prepare API Credentials

The first thing you need to do, if you haven’t done so already, is join the eBay developer program.  It only takes a few minutes and it’s completely free.  No coding is involved with this step at all, so I won’t spend too much time here, but I will quickly lay out what you’ll need to do from within your eBay developer account.

1. Create a set of keys for both the sandbox and production servers.  These keys will include a DevID, AppID, and a CertID.
2. Once you’ve created a set of keys, you need to generate an eBay Authentication Token.  Auth tokens are associated with a set of keys, so you’ll need to generate an auth token for each set of keys you might be using.
3. Click in to the Application Settings tab within your eBay developer account and follow the steps to customize the eBay user consent form to your liking.  This includes options like your company name, logo, and website URL.

Once these steps have been completed you’ll need to make the keys and the authentication token available to your application.  I like to use a configuration file within the project or a database table to store auth tokens.

This token represents the eBay account that should be used for the API call being made at that time, so it’s important that you manage these accurately if you’re building apps that many different users will utilize.

Step 2 – Generate a Request to Send to eBay

This is the most involved part in the process, but not because it’s difficult.  Building the XML request is actually very simple, but it can be a little bit time consuming depending on which calls you’re working with and the details that you need to include your request.

First, though, we simply need to build some headers to pass along with our request to eBay.  Here is a very simple snippet of code that will do exactly that.

// Create headers to send with CURL request.

$headers = array
(
	'X-EBAY-API-COMPATIBILITY-LEVEL: ' . $compat_level,
	'X-EBAY-API-DEV-NAME: ' . $dev_id,
	'X-EBAY-API-APP-NAME: ' . $app_id,
	'X-EBAY-API-CERT-NAME: ' . $cert_id,
	'X-EBAY-API-CALL-NAME: ' . $call_name,
	'X-EBAY-API-SITEID: ' . $site_id,
);

This code includes your API credentials as well as the eBay site ID and API version that you’re currently working with and loads each header value into an array.  The array will then be passed in to the CURL request object we use for the eBay request in step 3.

Now we can focus on building our actual XML request.  Don’t let this part scare you if you’re not familiar with XML.  All we’ll be doing here, essentially, is copying the request format from eBay’s documentation and filling in the blanks with our own data.  Simple enough, right?  Let’s take a look.

Every eBay XML request follows the same similar format that can be template as follows:

<?xml version="1.0" encoding="utf-8"?>
  <CallName xmlns="urn:ebay:apis:eBLBaseComponents">
    <RequesterCredentials>
    <eBayAuthToken> string </eBayAuthToken>
    </RequesterCredentials>
    <!-- Additional Request Elements -->
  </CallName>

As you can see here, this is a standard XML format with the use of a namespace for eBay.  It opens with an element that matches the API call you’re making (so you’d replace CallName with the name of the call you’re making), and it includes the eBay auth token for the requesting account within a <RequesterCredentials> node.

Below that, we’d simply fill in the in the actual request elements necessary for that request to complete it.  At this point you might be asking yourself, how do I know what request elements to include in my XML?

To answer that question, I’d like to direct you towards the eBay API Call Reference Guide.  This is a complete list of every API call that eBay currently offers and will provide us with all of the information we need in order to build our request.  When I’m working with eBay projects, this reference is pretty much always open in a browser tab on my machine so I can refer to it quickly and easily.  I’d recommend the same during your own development as you will find yourself using it a lot.  We’ll get into the reference guide in more depth in part 2 of this series when we begin to build some requests from scratch.

Step 3 – Send the Request to eBay Using CURL

This is another very simple step that we can accomplish with the use of a short snippet of code.

// Send request to eBay and load response in $response

$connection = curl_init();
curl_setopt($connection, CURLOPT_URL, $api_endpoint);
curl_setopt($connection, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($connection, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($connection, CURLOPT_HTTPHEADER, $headers);
curl_setopt($connection, CURLOPT_POST, 1);
curl_setopt($connection, CURLOPT_POSTFIELDS, $xml_request);
curl_setopt($connection, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($connection);
curl_close($connection);

This code simply creates a CURL request object and loads up the necessary CURL options for this call.  As you can see, we’re utilizing our $headers array within one of the CURL options as I mentioned we would be doing previously.

This code will handle sending the XML request to eBay and will receive the response, an XML string, back in the $response parameter.  All we have to do at this point is pull out any necessary data and process it accordingly.

Par 4 – Parsing thte XML Response from eBay

This step is actually the one that I used to fear the most.  Once I understood the basics of the Document Object Model (DOM) I realized it was actually a very simple thing to do.  Don’t let DOM scare you the way I did.  It’s really not that hard.

There are many lengthy guides on the use of DOM in PHP.  If you want to fully understand DOM inside and out, I’ll let you take a look at those guides rather than re-create the lessons here.  The one thing I will say is that it allows a developer to search through a document and pull out information based on XML tag names or attribute names and values, which is exactly what we’ll be doing with it here.

I’ll show you a quick sample of what to expect with PHP and DOM, and then we’ll get into more detail as we build some actual requests in part 2.  A typical DOM setup looks like this.

// Create DOM object and load eBay response

$dom = new DOMDocument();
$dom->loadXML($response);// Parse data accordingly.
$ack = $dom->getElementsByTagName('Ack')->length > 0 ? $dom->getElementsByTagName('Ack')->item(0)->nodeValue : '';
$eBay_official_time = $dom->getElementsByTagName('Timestamp')->length > 0 ? $dom->getElementsByTagName('Timestamp')->item(0)->nodeValue : '';

Here, we create a new DOM object and then load our XML response from eBay into this object.  Then, we use the getElementsByTagName() function to pull out tags that we’re interested in.  In this case I’m interested in the value for Ack, which will tell us whether or not the call was successful.  This code will actually look for an <Ack> element in the XML response, and if it finds it, it will load it into the $Ack PHP variable.  If it does not find it, the $Ack variable will still be created, but it will be an empty value. The same thing is happening for eBay_official_time.

We will cover this in a lot more depth in part 2 of this article, so get ready to see all of this in action!

Featured PayPal Products and Services