The eBay API

The eBay API allows you to perform business transactions efficiently and securely by using XML as the data format and HTTPS as the transport protocol.

To use the API, you'll have to register at the developer site, where you will retrieve your developer and application keys to access the API.

The eBay API uses a request token, similar to session ids (but much securer) for authentication. Your application will never receive the user-id and password directly, as this would open a lot of security holes. Instead the user will login at the ebay site, which will direct him back to your application and pass you his unique session identifier.

More on the eBay API can be found at: http://developer.ebay.com

Services_Ebay

Services_Ebay provides an easy-to-use wrapper class that enables you to transparently call any function provided by the eBay API.
It relies on PHP5 with curl or OpenSSL support enabled.

A small example

<?php

require_once 'Services/Ebay.php';

$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

$ebay = new Services_Ebay($session);
echo $ebay->GeteBayOfficialTime();
?>

This will fetch and output the current eBay time.

The main goal of Services_Ebay was to integrate the API into the way PHP works, so you do not have to create tons of objects that exchange data, you just tell the eBay object what you want to do. Think of it as something like simpleEbay (but with all the features eBay provides).

Architecture overview

The package consists of the following parts:

• The Services_Ebay class
• The Services_Ebay session
• A collection of API calls
• A collection of models

The Services_Ebay class

This class acts as a factory for the models and API calls as well as a proxy to the eBay API. Using PHP5's overloading capabilities, you will find yourself calling methods on this class that do not exist in the class definition.
Instead Services_Ebay will dispatch your request to one of the numerous API-calls which are loaded on demand. This keeps the package extendible and ensures that only the code that is really needed will be loaded.
Furthermore the class provides constants that may be used with some of the API calls.

The Services_Ebay session

The session object maintains the authentication and communication with the API. Whenever you want to call a method, you'll have to pass the session object, which serializes a call to XML, sends it to the eBay server and deserializes the result.
For this task, the session uses a Transport object that is interchangeable. Currently cURL is used, I'm evaluating streams and HTTP_Request.

The API-Calls

<?php

require_once 'Services/Ebay.php';

$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

$call = Services_Ebay::loadAPICall('GetEbayOfficialTime');
$result = $call->call($session);

echo $result;
?>

<?php

require_once 'Services/Ebay.php';

$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

$ebay = new Services_Ebay($session);
echo $ebay->GeteBayOfficialTime();
?>

Currently I implemented more than 50 API-calls, about 20 are left to go. You can take a look at all the calls that have been implemented in CVS.

There are always two ways of passing arguments to a call:

• passing the most important parameters as scalar values
• passing an associative array

<?php

$call = Services_Ebay::loadAPICall('GetAccount');
$call->describeCall();
?>

API-Call : GetAccount
Parameters (max. 6)
 AccountPageType(no default value)
 Period(no default value)
 BeginDate(no default value)
 EndDate(no default value)
 PageNumber(no default value)
 Currency(no default value)

API-calls provide nearly the same functionality as the eBay website, only placing bids or buying items is not possible with the API (this is not a drawback of Services_Ebay, this is not implemented by the eBay-API).

The Models

<?php

$user = $eBay->getUser('superman-74');
echo $user->Email;
?>

<?php

$feedback = $ebay->GetFeedback('loislane-74', Services_Ebay::FEEDBACK_VERBOSE);
print_r($feedback->toArray());

foreach ($feedback as $entry) {
    echo $entry;
    echo "<br />";
}
?>

<?php

$item = Services_Ebay::loadModel('Item', null, $session);
$item->Category = 57882;
$item->Title = 'Supergirls\'s cape';
$item->Description = 'Another test item';
$item->Location = 'At my home';
$item->MinimumBid = '1000.0';

$item->VisaMaster = 1;

$result = $ebay->AddItem($item);

if ($result === true) {
    echo 'Item has been added with ItemId: '.$item->Id.' and ends on '.$item->EndTime.'<br />';
} else {
    echo 'An error occured while adding the item.';
}
?>

<?php

$item->AddToDescription('This can also be done using $eBay->AddToItemDescription($id, $text);');
?>

Error handling

Nearly no error handling has been implemented, as Services_Ebay is a PHP5-packages I wanted to await the outcome of the error handling RFC. I plan on converting serious errors to exceptions, while integrating PEAR_ErrorStack for warnings. Currently all API-errors result in an exception.

More examples

I'm not able to show all that's possible in the proposal itself as there are already 50+ API calls and 15+ models that provide even more features.
There is an example for every API call available, take a look at the sourcecode in CVS or test them online

The Future

I've been working on this project for about two weeks and I intend to put a lot more effort in this project. I'll add all missing API calls and improve the existing models to make the API more intuitive to use.

Possible feature additions yould be:

• Validation of API-call arguments
• Validation of model properties
• Decorators for the models

Accepted by eBay?

I'm in contact with Adam Trachtenberg, technical evangelist at eBay and he is amazed by the package so far. He is constantly reviewing the source and helping me with any problems I may run into.

Competing packages

There's the eBay Acellerator Toolkit for PHP, which provides a similar functionality as Services_Ebay.
After evaluating the projects I found the following differences:

• Services_Ebay is PHP5-only while PHPAT is focussing on PHP4
• Services_Ebay is fully PEAR compliant, while PHPAT needs some adjustements
• Services_Ebay has a lot less code by relying on overloading objects instead of providing setters/getters for each property
• Services_Ebay always uses the same method and argument names as the eBay API, while PHPAT adjusted the names in some cases

These observations may be biased feel free to compare these two projects.