Trading API
 

Executing Your First C# Call

This section walks through the basics of executing a call—specifically, the GeteBayOfficialTime call—for the eBay SOAP API. The GeteBayOfficialTime call is the simplest call in the API. It can be used to synchronize the time in your system with eBay official time or as a simple way to verify whether you are communicating with the eBay API servers.

There are just four steps:

Step 1: Set Up a Programming Environment

Step 2: Add the Code

Step 3: Run the Sample

Step 4: Understand the Example

Step 5: Understand the SOAP Messages

The code examples in this chapter are in C#, however, you can use almost any language to access the eBay SOAP API.

Prerequisites

Before you execute your first SOAP API call:

Step 1: Set Up a Programming Environment

The specific steps that you must perform to set up your environment will vary depending on what programming language you use. One important requirement common to all languages is support for SSL. This example was written in C# Microsoft Visual Studio .NET.

In Visual Studio, create a project file, then add a web reference to it (Solution Explorer, right-click, Add Web Reference). Enter the URL to the latest eBay WSDL:

https://developer.ebay.com/webservices/latest/ebaySvc.wsdl

Then, click Add Reference. This generates stubs from the eBay WSDL and adds them to the project so that they are available to your source files. You can see them in the Class View.

Step 2: Add the Code

Now you will add the code that calls the SOAP API. Create a source file named GeteBayOfficialTime.cs and paste the following code into it.

Example 3-1 GeteBayOfficialTime.cs

using System;
using TesteBaySoap405.com.ebay;     // use your project name here
namespace TesteBaySoap405           // use your project name here
{
  class GeteBayOfficialTime
  {
    [STAThread]
    static void Main(string[] args)
    {
       string endpoint = "https://api.sandbox.ebay.com/wsapi";
       string callName = "GeteBayOfficialTime";
       string siteId = "0";
       string appId = "yourAppId";     // use your app ID
       string devId = "yourDevId";     // use your dev ID
       string certId = "yourCertId";   // use your cert ID
       string version = "405";
       // Build the request URL
       string requestURL = endpoint
       + "?callname=" + callName
       + "&siteid=" + siteId
       + "&appid=" + appId
       + "&version=" + version
       + "&routing=default";
       // Create the service
       eBayAPIInterfaceService service = new eBayAPIInterfaceService();
       // Assign the request URL to the service locator.
       service.Url = requestURL;
      // Set credentials
      service.RequesterCredentials = new CustomSecurityHeaderType();
      service.RequesterCredentials.eBayAuthToken = "yourToken";    // use your token
      service.RequesterCredentials.Credentials = new UserIdPasswordType();
      service.RequesterCredentials.Credentials.AppId = appId;
      service.RequesterCredentials.Credentials.DevId = devId;
      service.RequesterCredentials.Credentials.AuthCert = certId;
      // Make the call to GeteBayOfficialTime
      GeteBayOfficialTimeRequestType request = new GeteBayOfficialTimeRequestType();
      request.Version = "405";
      GeteBayOfficialTimeResponseType response = service.GeteBayOfficialTime(request);
      Console.WriteLine("The time at eBay headquarters in San Jose, California, USA, is:");
      Console.WriteLine(response.Timestamp);
    }
  }
}

You must modify some of the code with your information in order for it to work:

Step 3: Run the Sample

Now you can build and run the sample.

  1. From the menu, choose Build, then Build Solution.
  2. Choose Debug, then Start Without Debugging.

You should see output like this:

  The time at eBay headquarters in San Jose, California, USA, is:
  4/29/2005 6:21:54 PM
  Press any key to continue

Step 4: Understand the Example

This sample takes four basic steps that you need to use in any client application that calls the eBay web service. The web service client should:

  1. Build the request URL that contains the location of the eBay web service, the call name, and other parameters that make the call.

    The request URL should contain the URL to the eBay service, the call name, the site ID, your application ID, the WSDL version number, and the special parameter routing=default. The routing=default ensures that your call reaches the eBay single-namespace WSDL.

    Example 3-2 Build the Request URL

           string endpoint = "https://api.sandbox.ebay.com/wsapi";
           string callName = "GeteBayOfficialTime";
           string siteId = "0";
           string appId = "yourAppId";     // use your app ID
           string devId = "yourDevId";     // use your dev ID
           string certId = "yourCertId";   // use your cert ID
           string version = "405";
           // Build the request URL
           string requestURL = endpoint
           + "?callname=" + callName
           + "&siteid=" + siteId
           + "&appid=" + appId
           + "&version=" + version
           + "&routing=default";
    
  2. Create a service locator object and pass it the request URL.

    The service object that is an instance of eBayAPIInterfaceService allows you to make the call. You need to create it and pass it the request URL.

    Example 3-3 Create the Service Locator Object

           // Create the service
           eBayAPIInterfaceService service = new eBayAPIInterfaceService();
           // Assign the request URL to the service locator.
           service.Url = requestURL;
    
  3. Set credentials.

    This part of the sample sets your authentication token and your three Sandbox keys. You can choose to hard-code them for a test call, read them from a properties file, or use some other technique, but they must be set in CustomSecurityHeaderType and UserIdPasswordType.

    The token must be current and correct for the Sandbox keys. If your token has expired, the call will return an error. In that case, obtain a new token.

    Example 3-4 Set Credentials

          // Set credentials
          service.RequesterCredentials = new CustomSecurityHeaderType();
          service.RequesterCredentials.eBayAuthToken = "yourToken";    // use your token
          service.RequesterCredentials.Credentials = new UserIdPasswordType();
          service.RequesterCredentials.Credentials.AppId = appId;
          service.RequesterCredentials.Credentials.DevId = devId;
          service.RequesterCredentials.Credentials.AuthCert = certId;
    
  4. Make the call.

    For the call you plan to use, create an instance of the request type. Set its Version variable and any other variables that are required or important for the call. Then, create an instance of the response type. Make the call on the service object, passing it the request object and storing the result in the response object.

    Note that the time returned is the official time at eBay headquarters in San Jose, California, in either Pacific Standard Time or Pacific Daylight Time.

    You can also write similar lines that execute a different call here. Make sure to set all needed variables in the request object. If you are making a call that involves buying, selling, or obtaining user information, you must create test users in the Sandbox first (See Sandbox for more information).

    Example 3-5 Make the Call

          // Make the call to GeteBayOfficialTime
          GeteBayOfficialTimeRequestType request = new GeteBayOfficialTimeRequestType();
          request.Version = "405";
          GeteBayOfficialTimeResponseType response = service.GeteBayOfficialTime(request);
          Console.WriteLine("The time at eBay headquarters in San Jose, California, USA, is:");
          Console.WriteLine(response.Timestamp);
    

Step 5: Understand the SOAP Messages

The SOAP request message to GeteBayOfficialTime looks like Example 3-6. The credentials are set in the SOAP header according to the structure of RequesterCredentials in the eBay WSDL, while the request to GeteBayOfficialTime is made in the SOAP body.

Example 3-6 SOAP Request Message

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
    <RequesterCredentials soapenv:mustUnderstand="0" xmlns="urn:ebay:apis:eBLBaseComponents">
       <eBayAuthToken>ABC...123</eBayAuthToken>
       <ns:Credentials xmlns:ns="urn:ebay:apis:eBLBaseComponents">
        <ns:DevId>someDevId</ns:DevId>
        <ns:AppId>someAppId</ns:AppId>
        <ns:AuthCert>someCertId</ns:AuthCert>
       </ns:Credentials>
    </RequesterCredentials>
  </soapenv:Header>
  <soapenv:Body>
    <GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <ns1:Version xmlns:ns1="urn:ebay:apis:eBLBaseComponents">405</ns1:Version>
    </GeteBayOfficialTimeRequest>
  </soapenv:Body>
</soapenv:Envelope>

The SOAP response from GeteBayOfficialTime looks like Example 3-7. Note that the response in the SOAP body contains the eBay official time defined in GeteBayOfficialTime and also values (such as Ack, CorrelationID, Version, and Build) defined in AbstractResponseType.

Example 3-7 SOAP Response Message

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
      <Timestamp>2005-05-02T00:07:22.895Z</Timestamp>
      <Ack>Success</Ack>
      <CorrelationID>
        00000000-00000000-00000000-00000000-00000000-00000000-0000000000
      </CorrelationID>
      <Version>405</Version>
      <Build>20050422132524</Build>
    </GeteBayOfficialTimeResponse>
  </soapenv:Body>
</soapenv:Envelope>