|» Metadata||» Status|
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 provides an easy-to-use wrapper class that enables you to transparently call any function provided by the eBay API.
A small exampleBefore explaining the architecture of the package, let's start off with a small but powerful example.
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).
The package consists of the following parts:
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.
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.
The API-CallsEach API call is encapsulated within one class, which is derived from an API-Call base class. The calls can be instantiated and called directly without using a proxy class, or you may use Services_Ebay which does most of the work for you.Â´
The following example shows how to retrieve the current time without calling a method on the proxy:
This does the same:
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:
If you are unsure about the parameter order of a call, you may ask the call-object to display a description:
This will display:
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 ModelsThe Services_Ebay models provide PHP objects that are local representations of the entities used at the eBay website. These include users, items, messages, transactions, feedback entries, lists and many more.
The models use SPL and overloading to be accessed in many ways. That means you may read and write properties of users by accessing the properties of the PHP object:
Services_Ebay_Model::toArray() will return an associative array of all properties of the user/item or whatever if you prefer using arrays instead of objects.
Some models allow iterating, like the Feedback model:
When iterating a Feedback, you will get feedback entries, objects that may be echo'd to STDOUT or used in many other fashions, like retrieving the item specifics for the feedback with $entry->getItem().Some API calls allow you to pass a model:
Furthermore models provide shortcuts to API calls like:
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.
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.
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:
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.
There's the eBay Acellerator Toolkit for PHP, which provides a similar functionality as Services_Ebay.
These observations may be biased feel free to compare these two projects.
|» Dependencies||» Links|
|» Timeline||» Changelog|