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:

Make sure you have your Sandbox keys available, as you will need them in order to make an XML API call.

Your Sandbox keys are the three IDs (DevID, AppID, and CertID) you generated after you joined the eBay Developers Program (see Sandbox for information on how to generate these keys). If you are not the primary contact for your program membership, you may need to get these keys from the person who originally signed up. If you are the primary contact and you cannot find your keys, please complete a request on the eBay Developers Program site to have the keys sent to you.
Register for a user account on the eBay Sandbox site (sandbox.ebay.com), if you do not have one already. This account will be used to create an authentication token for the three Sandbox keys. (For this example that calls GeteBayOfficialTime, you do not need to create a test user in the Sandbox).
Obtain an authentication token using the Authentication Token Tool on the eBay site. You will be asked to enter your keys and your login credentials to the eBay site. The tool will return a token.

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:

Use your project name in the using and namespace statements at top.
Add your developer key, application key, and certificate key. Note that you are hard-coding them only for this simple example. In a production application, your code would likely read them from a properties file or use some other loading technique.
Add your token.

Step 3: Run the Sample

Now you can build and run the sample.

From the menu, choose Build, then Build Solution.
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:

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";

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;
```
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;
```
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>