Trading API
 

Executing Your First eBay SDK for .NET Call

This section contains examples involving GetUser calls from the eBay SDK for .NET. The examples make use of classes whose source files are located here: C:\Program Files\eBay\<SDK_install_dir>\Source\eBay.Service.SDK\Core\Sdk. These classes provide underlying functionality for calls made using the SDK.

This section contains the following subsections:

Classes Underlying Calls

The ApiCall, ApiContext, and ApiCredential classes are the primary classes underlying calls made using the SDK.

ApiCall

This class is the base class that defines functionality common to all API call classes, such as specifying an API context object, setting detail levels, and holding a response object.

The functionality common to all the API call classes includes:

ApiContext

This class defines the context of an API call. The context is set up once for all API call classes in one session. The context defines such environment factors as the target eBay API server URL, user authentication data, and API call logging. An ApiContext object is required input for the constructor of every API call class.

Thus, before an API call object can be used to make an API call, the application must create and define an ApiContext object. It is then assigned to the ApiContext property of the API call object. This must be done prior to invoking the API call object's execution method.

For an ApiContext object, values are needed for its properties. When an API call is made, the values specified in the ApiContext object are used for the following purposes, among others:

An application can set up a single ApiContext object and reuse it for multiple API calls made with different API call objects. This is useful if the application needs to use the TotalCalls property to track the number of calls made. It also allows for specifying the server URL, setting up call logging, and specifying authentication credentials once for all calls the application session will make.

ApiCredential

This class enables you to provide authentication data for a call's requesting user. Three key properties are ApiAccount, eBayAccount, and eBayToken. An ApiCredential object fills the ApiCredential property of an ApiContext object.

The ApiCredential object is integral to the ApiContext object. The ApiCredential object contains either the authentication token or the username and password used to authenticate the requesting user (not both a token and a username/password). The ApiCredential object also enables you to set up a token event listener object to detect token expiration events.

For the requesting user's authentication data, you can specify the authentication token for the user in the eBayToken property. Or you can specify the user's eBay username and password in the eBayAccount property. Whichever authentication method is used, one set of authenticating data must always be specified.

The ApiCredential object is also used to pass application credentials (developer ID, application ID, and certificate). This is done in the ApiAccount property. (Application credentials are only specified if user authentication is done by username and password.)

An ApiCredential object can be created and configured once and then used for multiple calls with the same API context object.

Before an ApiCredential object can be used, the following conditions must be met:

Using a Wrapper Class in the eBay SDK for .NET

GetUserCall call has few input fields, so it is fairly easy to use. In the code examples, the call is sent to the US eBay site. The GetUserCall response has many useful fields. The examples in this section examine only a few of them for demonstration purposes.

The following examples are in C#, but similar steps would need to be performed regardless of the programming language used. For this section, it is also assumed that you will be using Visual Studio.NET to write and execute the code, although this is not required to use the eBay SDK for .NET.

Prerequisites

Before you execute your first eBay SDK for .NET call:

Step 1: Configure Visual Studio.NET

  1. Start Microsoft Visual Studio .NET.
  2. Create a New Project:
    1. Click New Project on the Start Page.
    2. In the New Project window, select Visual C# Projects from the Project Types window.
    3. In the Templates Window select Console Application.
    4. In the Name field, enter ExecutingYourFirstCall and click OK.
  3. Add a Reference to the eBay SDK for .NET assembly:
    1. In the Solution Explorer, right-click the References folder and select Add Reference:

    2. With the .NET tab selected, click Browse.
    3. In the Select Component dialog, browse to the eBay SDK for .NET home directory (by default: C:\Program Files\eBay\<SDK_Install_Dir>).
    4. Select the eBay.Service.dll assembly. Click Open. The assembly now appears under Selected Components:

    5. Click OK.

      The Reference to the assembly now appears under the Reference folder in the Solution Explorer.

If you choose to develop with the eBay SDK for .NET using Visual Studio .NET, you will follow these same steps to create a new project, no matter which .NET language you use.

For this example, you only need to add a Reference to the eBay.Service.dll assembly. For any project you develop with the eBay SDK for .NET you will need a Reference to this assembly. Depending on features of the eBay SDK for .NET that you use, you also may need to add a Reference to the following eBay SDK for .NET assembly: eBay.Service.SDK.Attribute.dll (Attributes Library).

Step 2: Write the Code

Now you will write the code that makes the call to GetUser. In the default Class1.cs file that is created in your project, select all the existing text and replace it with the following:

Example 3-1 Class1.cs

using System;

using eBay.Service.Core.Sdk;
using eBay.Service.Call;
using eBay.Service.Core.Soap;

namespace ExecutingYourFirstDotNETSDKCall
  {
  class ExecuteCall
  {
    static void Execute()
    {
      ApiContext context = new ApiContext();
      // Credentials for the call
      context.ApiCredential.ApiAccount.Developer = "yourdevname";
      context.ApiCredential.ApiAccount.Application = "yourappname";
      context.ApiCredential.ApiAccount.Certificate = "yourcertname";
      context.ApiCredential.eBayToken = "yourtoken";
      // Set the URL
      context.SoapApiServerUrl = "https://api.sandbox.ebay.com/wsapi";
      try
      {
        // Create the call object
        GetUserCall call = new GetUserCall(context);
        String requestedUser = "yoursandboxuser";
        UserType user = call.GetUser(requestedUser);
        // Print the results to standard out
        Console.WriteLine("eBay Time: " + call.AbstractResponse.Timestamp.ToString());
        Console.WriteLine("User retrieved: " + user.UserID);
        Console.WriteLine("Feedback score: " + user.FeedbackScore);
        Console.WriteLine("Feedback star: " + user.FeedbackRatingStar);
        Console.WriteLine("Seller level: " + user.SellerInfo.SellerLevel);
        Console.WriteLine("User's registered site: " + user.Site);
      }
      catch (ApiException e)
      {
         Console.WriteLine("Problem getting user. Errors listed below.");
         foreach(ErrorType error in e.Errors)
        {
           Console.WriteLine("Error: " + error.ShortMessage);
           Console.WriteLine("Message: " + error.LongMessage);
        }
      }
      catch (Exception e)
      {
        Console.WriteLine("Unexplained error in making the API call" + e.StackTrace);
      }
    }
    [STAThread]
    static void Main(string[] args)
    {
      Execute();
    }
  }
}

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

After you have updated this information, compile the code by selecting Build > Build Solution. If there are any compilation errors, double-check your code and fix any problems.

Step 3: Run the Example

Run the example by selecting Debug > Start Without Debugging:

This launches a Command Prompt window. After a few seconds, you should see output like the following:

Example 3-2 GetUser Example Output

eBay Time: 3/3/2005 9:12:09 AM
User retrieved: xyzuser
Feedback score: 13
Feedback star: Yellow
Seller level: None
User's registered site: US
Press any key to continue

Step 4: Understand the Example

The code used in this example is very simple. Let's examine each of the pieces of the code in more detail:

Example 3-3 Namespaces

using System;

using eBay.Service.Core.Sdk;
using eBay.Service.Call;
using eBay.Service.Core.Soap;

Any code written using the eBay SDK for .NET is likely to require types from the eBay.Service.* namespaces. The types in these namespaces are all defined in the eBay.Service.dll assembly.

Example 3-4 ApiContext

      ApiContext context = new ApiContext();
      // Credentials for the call
      context.ApiCredential.ApiAccount.Developer = "yourdevname";
      context.ApiCredential.ApiAccount.Application = "yourappname";
      context.ApiCredential.ApiAccount.Certificate = "yourcertname";
      context.ApiCredential.eBayToken = "yourtoken";
      // Set the URL
      context.SoapApiServerUrl = "https://api.sandbox.ebay.com/wsapi";

For any call you make using the eBay SDK for .NET, you must create an ApiContext object. This object contains information about the application making the call (the developer keys), the user on whose behalf the application is making the call (the token), and the URL where the call is being sent. This object is passed to the constructor of the call object that you create, as you will see next:

Example 3-5 Making the Call

      try
      {
        // Create the call object
        GetUserCall call = new GetUserCall(context);
        String requestedUser = "yoursandboxuser";
        UserType user = call.GetUser(requestedUser);
        // Print the results to standard out
        Console.WriteLine("eBay Time: " + call.AbstractResponse.Timestamp.ToString());
        Console.WriteLine("User retrieved: " + user.UserID);
        Console.WriteLine("Feedback score: " + user.FeedbackScore);
        Console.WriteLine("Feedback star: " + user.FeedbackRatingStar);
        Console.WriteLine("Seller level: " + user.SellerInfo.SellerLevel);
        Console.WriteLine("User's registered site: " + user.Site);
      }

After the GetUserCall object is created, the GetUser method is called on it, passing in the string that defines the user to retrieve. The method returns a UserType object that contains the user data:

This data is printed to the command line using Console.WriteLine

Any errors in the call are caught by one of two catch blocks:

Example 3-6 Error Handling

      catch (ApiException e)
      {
         Console.WriteLine("Problem getting user. Errors listed below.");
         foreach(ErrorType error in e.Errors)
        {
           Console.WriteLine("Error: " + error.ShortMessage);
           Console.WriteLine("Message: " + error.LongMessage);
        }
      }
      catch (Exception e)
      {
        Console.WriteLine("Unexplained error in making the API call" + e.StackTrace);
      }
    }

If the call throws an ApiException, you can retrieve the API errors from the Errors property. An application can use the data in this property to determine how to retry the call with different data that will not cause an error. With the GetUser call, an application could catch errors that indicate that a user could not be found and prompt the end user to try entering another user name.

Congratulations! You have successfully retrieved data from eBay using the wrapper class for the GetUser call.

Using a Request Object Directly in a Windows Environment

This example demonstrates how to use a SOAP API request object directly, without using an SDK wrapper class.

Prerequisites

Before starting this example, make sure you have your Sandbox Keys handy.

Retrieve your Sandbox Keys from the My Account page (https://developer.ebay.com/DevZone/account/). For more information, see Sandbox). 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.

Additionally, you need to create a Sandbox test user. Only test users can invoke calls in the Sandbox. For more information, see Create a test Sandbox user.

When you create a test user, you need an authentication token for the test user (see Sandbox).

Step 1: Create a Project in Visual Studio.NET

  1. Start Microsoft Visual Studio .NET.
  2. Create a New Project:
    1. Click New Project on the Start Page.
    2. In the New Project window, select Visual C# Projects from the Project Types window.
    3. In the Templates Window select Console Application.
    4. In the Name field, enter ConsoleApplication1 and click OK.
  3. Add a web reference to the latest eBay WSDL at https://developer.ebay.com/webservices/latest/ebaySvc.wsdl.

    Name it eBay. The web reference should appear under the Web References folder in the Solution Explorer.

Step 2: Write the Code

Now you will write the code that makes the GetUser call. In the default Class1.cs file that is created in your project, select all the existing text and replace it with the following:

Example 3-7 Class1.cs

using System;
using ConsoleApplication1.eBay;

namespace ConsoleApplication1
  {
  class Class1
  {
    [STAThread]

    static void Main(string[] args)
    {
      string endpoint = "https://api.sandbox.ebay.com/wsapi";
      string callName = "GeteBayOfficialTime";
      string siteId = "0";
      string devId = "yourdevname";
      string appId = "yourappname";
      string certId = "yourcertname";
      string version = "421";

      // 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 = "usertoken";
      service.RequesterCredentials.Credentials = new UserIdPasswordType();
      service.RequesterCredentials.Credentials.AppId = appId;
      service.RequesterCredentials.Credentials.DevId = devId;
      service.RequesterCredentials.Credentials.AuthCert = certId;

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

      GetUserRequestType getUser = new GetUserRequestType();
      getUser.UserID = "yoursandboxuser";
      getUser.Version = "421";

      requestURL = endpoint
      + "?callname=" + "GetUser"
      + "&siteid=" + siteId
      + "&appid=" + appId
      + "&version=" + version
      + "&routing=default";

      service.Url = requestURL;

      GetUserResponseType response2 = service.GetUser(getUser);
      Console.WriteLine("The user's Feedback score is:");
      Console.WriteLine(response2.User.FeedbackScore.ToString());
      Console.Read();
    }
  }
}

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

After you have updated this information, compile the code by selecting Build > Build Solution. If there are any compilation errors, double-check your code and fix any problems.

Step 3: Run the Example

Run the example by selecting Debug > Start Without Debugging:

This launches a Command Prompt window. After a few seconds, you should see output like the following:

Example 3-8 GetUser Example Output

The time at eBay headquarters in San Jose, California, USA, is
8/23/2005 11:15:41 AM
The user's Feedback score is:
16

Congratulations! You have accessed the SOAP API directly, without using an SDK wrapper class.

For information on serializing objects such as an Item object, search the Knowledge Base for "serialization" at the following location:

https://developer.ebay.com/DevZone/support/KnowledgeBase.asp/