Using the eBay SDK

by Jeffrey McManus
11/10/2003

Unless you've been living in a cave, you probably already know that eBay enables people and businesses to buy and sell items online. But you might not have known that you can write software applications that integrate with eBay through a handy set of .NET components. This article will give you an overview of how to write apps using the eBay SDK for .NET, what you can do with the SDK, and what developers are doing with it today.

eBay provides a cross-platform, XML-over-HTTPS API that enables you to create eBay apps on any platform. For lucky .NET developers, there's also an SDK for .NET, downloadable for free from developer.ebay.com, that wraps the XML-based API in nice, sanitary objects for your protection. Here's a diagram that shows how this all fits together.

Architecture stack showing the eBay API and SDK in the context of eBay.com

The nice thing about the API and SDK is the fact that you aren't limited to one or the other. In fact, many of the XML responses returned by the API are exposed through the SDK (there's an example of this at the end of this article). So you get the programmable ease of objects and the flexibility of XML documents -- the best of both worlds.

Related Reading eBay Hacks 100 Industrial-Strength Tips & Tools By David A. Karp

What kind of apps are eBay developers creating today? In general, there are three scenarios:

1. By day, you're an eBay buyer or seller; by night, you're a superhero coder with your own custom software that helps you efficiently manage your eBay listings.
2. You're a retailer or manufacturer with a warehouse full of fine products that you want to convert into bags of cash, so you write an application that connects your existing inventory system with eBay.
3. You're a solution provider looking to help out with one of the above scenarios.

The eBay Platform is one of the biggest commercial service-oriented architectures on the Web today. More than 15 million XML-based requests are handled through the API. Nearly 40% of all item listings on eBay.com come in through the API, and thousands of businesses and individuals use it to make their lives on eBay easier. In fact, eBay uses the API itself for various applications and tools; one of the biggest users of the API is PayPal. The rest of this article will provide some lightweight code examples to show how this is done.

Getting Started in the Sandbox

eBay provides a test environment -- known as the sandbox -- that enables you to create and test your eBay applications without interacting with the real eBay.com site. Located at sandbox.ebay.com, the sandbox is a stripped-down version of eBay designed specifically for third-party software developers, providing most (but not all) of the functionality of the real eBay.com site. We'll use the sandbox for the demonstration code described in this article.

Making Your First SDK Call

One call that's commonly used as a "hello world" example is GeteBayOfficialTime. This is a good place to start, because GeteBayOfficialTime is one of the simplest calls in the eBay API. Here's an example of a call to GeteBayOfficialTime:

void btnGetTime_Click(object sender, EventArgs e)
{
  ApiSession sess = CreateSession();
  GeteBayOfficialTimeCall timeCall = 
    new GeteBayOfficialTimeCall(sess);
  DateTime theTime = timeCall.GeteBayOfficialTime();
  MessageBox.Show(theTime.ToString());
}

Listing 1: Getting the official time from eBay using the SDK

You can see that the first step involves creating an instance of eBay.SDK.API.ApiSession, which is done in this example by calling a function called CreateSession (described in the next listing). Once you have an instance of ApiSession, you create an instance of GeteBayOfficialTimeCall by passing your ApiSession object to it. (This pattern of session management is repeated for most calls in the SDK, as we'll see in later examples.) From there you call the GeteBayOfficialTime method, which returns a .NET DateTime type. This is another subtle advantage to using the SDK: unlike the XML-based API, which returns everything in the form of untyped strings contained in the nodes of an XML document, the SDK returns typed values, so when you're dealing with types such as dates and decimal currency values, you don't have to fool around with parsing and casting data. Note that the time returned by GeteBayOfficialTime is GMT, so you may need to adjust for your time zone.

Next, let's take a look at the session object that this function needs to do its work. The ApiSession object requires six pieces of data:

• Your developer ID, developer certificate, and application ID (collectively known as your "developer keys"). You can get your own set of sandbox keys by signing up for free at developer.ebay.com.
• An eBay user ID and password. This is the account you use to sign up on eBay.com to buy and sell items. (In the sandbox, you create your own user account that's specific to the sandbox.)
• The address of the API server. For the sandbox, this is always https://api.sandbox.ebay.com/ws/api.dll.

Here's the code for the CreateSession function, which returns a populated instance of an ApiSession object.

ApiSession CreateSession() 
{
  // Get your DeveloperID, Certificate and App ID 
  // from http://developer.ebay.com
  ApiSession sess = new eBay.SDK.API.ApiSession();
  sess.Developer = MY_DEVELOPER_ID;
  sess.Certificate = MY_CERTIFICATE;
  sess.Application = MY_APP_ID;
  sess.RequestUserId = MY_EBAY_USERID;
  sess.RequestPassword = MY_EBAY_PASSWORD;
  sess.Url = "https://api.sandbox.ebay.com/ws/api.dll";

  return sess;
}
}

Listing 2: Creating an ApiSession object

For a real application, rather than hard-coding these values into constants as shown here, you'll probably want to store them in an App.Config file, retrieving them with calls to System.Configuration.ConfigurationSettings.

(At this point you may be asking yourself: Why do I need eBay to tell me what time it is? It's because of the auction listing format -- you may want to time precisely when a listing is going to start or end, so knowing what time it is according to eBay's clock is pretty important.)

Listing Items

Listing an item for sale on eBay is one of the most common operations performed by developers. Creating a listing using the SDK is a four-step process:

• Create an instance of the eBay.SDK.Model.Item.Item object and populate its properties with information about your item.
• Create an instance of the AddItemCall object, passing the ApiSession object to its constructor.
• Assign the Item object to the AddItemCall object's ItemToAdd property.
• Call the AddItem method of the AddItemCall object.

Here's how to create an Item object:

eBay.SDK.Model.Item.Item CreateItem(String title, 
                                    String description) 
{
  // Create a new EBay Item
  eBay.SDK.Model.Item.Item it = 
    new eBay.SDK.Model.Item.Item();
  
  // Set the properties
  it.SiteId = SiteIdEnum.US;
  it.Type = ItemTypes.Auction;
  it.Title = title;
  it.Description = description;
  it.Currency = CurrencyEnum.USDollar;
  it.Location = "San Jose, CA";
  it.Country = "us";
  it.CategoryId = 14111; // test auctions:general
  it.Quantity = 1;
  it.Duration = 7;
  it.MinimumToBid = 10.00m;
  it.BuyItNowPrice = 15.00m;
  it.ReservePrice = 0;
  it.PaymentTerms.SeeDescription = true;
  it.ShippingOptions.ShippingRange = ShippingRangeEnum.SiteOnly;
  it.ShippingOptions.ShippingPayment.SeeDescription = true;
  it.Uuid = new Uuid(true);
  
  return it;
}

Listing 3: Creating and populating the properties of an Item object

Lots of the properties are hard-coded, but of course you're free to supply your own values for things like location, quantity, and minimum bid price. (You can also list items in fixed-price format, as well, if you wish.)

Once you've created the Item object, you submit it to eBay using code like this:

void btnAddItem_Click(object sender, EventArgs e) 
{
  AddItemCall ai = new AddItemCall(CreateSession());
  ai.ItemToAdd = CreateItem(txtName.Text, txtDescription.Text);
  ai.ErrorLevel = ErrorLevelEnum.BothShortAndLongErrorStrings;
  
  try 
  {
    IFees fees = ai.AddItem();
    txtItemID.Text = ai.ItemToAdd.ItemId.ToString();
    txtListingFee.Text = fees.InsertionFee.ToString();
  } 
  catch(APIException ex) 
  {
    MessageBox.Show("API exception in AddItem. [" + 
      ex.Message + "]");
  }
  catch(Exception ex) 
  {
    MessageBox.Show("Exception in AddItem. [" + 
      ex.Message + "]");
  }
}

Listing 4. Listing an item for sale using AddItem

The return value of the AddItem method is an instance of IFees, which contains two useful properties: the ID of the newly listed item, and the fee charged to the seller by eBay to list the item. Naturally, it's important to handle exceptions when calling AddItem.

Finding Things

When you know the ID of an item on eBay, it's easy to locate. In the previous example, you could append the ID to the end of the URL http://cgi.sandbox.ebay.com/ws/eBayISAPI.dll?ViewItem&item= to go directly to the item's page. (Of course, you can also retrieve an item's details programmatically, as well.) But most folks don't navigate eBay that way -- instead, they use category-based navigation or the keyword search to find what they want. You can incorporate eBay search in your application by using the GetSearchResults call. Here's a simple example:

void btnSearch_Click(object sender, EventArgs e) 
{
  // Get a search object
  GetSearchResultsCall search = 
    new GetSearchResultsCall(CreateSession());
  
  // Set Query
  search.Query = txtSearch.Text;
  
  // Set the Results 
  // (can be up to 100; use paging to get more data)
  search.MaxResults = 20;    
  
  // Get the results
  IItemFoundCollection items = search.GetSearchResults();
}

Listing 5. Returning search results in the form of a typed collection

The Query property of the GetResultsSearchCall object indicates the expression used for the search. There are several additional options for searching -- you can search by price, product category, seller ID, and so forth. The maximum number of items returned in a single call is 100, but you can place additional calls to GetSearchResults to retrieve more pages of data if you want to get the whole enchilada.

You can see from the code that GetSearchResults returns a typed collection of ItemFound objects, which is great, but what if you want to get access to the raw XML retrieved by the call? Easy as pie. The GetSearchResultsCall object raises two events that expose the underlying XML for the call's request and response -- to capture the response XML, you simply create an instance of the appropriate delegate type (FilterXmlHandler) passing the address of an event handler to the delegate's constructor. Here's what the event handler looks like:

void Search_ResponseXml(Object Sender, FilterXmlEventArgs e) 
{
  txtSearchResults.Text = e.Xml.OuterXml.ToString();
}

Listing 6: Capturing search results in XML format using an event handler

As you can see, the FilterXmlEventArgs object has an Xml property, which is an instance of System.Xml.XmlDocument that represents the results returned from eBay. This event handler simply dumps the search XML out to a text box, but it would be a simple matter to perform client-side subsearches on this data using XPath, for example, or to transform it for display.

Listing and locating items just scratches the surface of what's available with the eBay SDK -- there are dozens more calls to manage various aspects of the eBay experience. In addition to the features discussed in this article, the SDK provides calls for viewing and leaving user feedback, managing an eBay store, accessing the personalized portal information contained in the "My eBay" section of eBay.com -- even a database synchronization library that lets you replicate and cache information that your application retrieves from eBay. There's a lot of goodness there for .NET developers, so if you're looking to start or accelerate a business on eBay, have at it!

References

• eBay Developer Site
• Source code

Jeffrey McManus is eBay's Senior Manager of Developer Relations and is the author of several books on software development.

---

Return to ONDotnet.com