Routing the Request

Topics:

Service Endpoints

HTTP Headers (XML API Only)

SOAP URL Parameters (SOAP API and SDKs Only)

Service Endpoints

All Trading API requests that you execute must be sent to the Sandbox or Production Gateway for the API. You specify the gateway URI (endpoint) in the request. If you are using the SOAP API, you append a query string that tells eBay how to route your request.

The Gateway URIs for Sandbox data and API calls are:

XML API Sandbox Gateway URI

https://api.sandbox.ebay.com/ws/api.dll

SOAP API Sandbox Gateway URI

https://api.sandbox.ebay.com/wsapi

The Gateway URIs for live, production data and API calls are:

XML API Production Gateway URI

https://api.ebay.com/ws/api.dll

SOAP API Production Gateway URI

https://api.ebay.com/wsapi

eBay requires that you use HTTPS/SSL when you execute calls in the Production environment. This ensures that data can be transferred securely between your application and the eBay platform. Although Sandbox data is simulated, you also need to use HTTPS/SSL when you execute calls in the Sandbox.

Note that although some of your developer keys are optional for certain calls, the full set of developer keys is required for GetTokenStatus and RevokeToken API calls. The tables in this section will give you more information about when specific information is required for a call.

See Standard Data for All Calls for the data required in all Trading API requests. See The Production and Sandbox Environments for general information about working in the Sandbox and Production environments.

Note: In the WSDL for the SOAP API, the service locator specifies eBay's Production SOAP gateway URI (the physical location of the service endpoint). In the service clause of the WSDL, you can see that the name of the service locator will be derived from eBayAPIInterfaceService. However, as the same WSDL is used both in the Sandbox and in Production, you should pass in the service endpoint yourself rather than obtaining it from the service locator.

Service Endpoints for Other eBay APIs

The following table lists the endpoints for the Finding and Shopping APIs. For the endpoints of other API, see their Making a Call documentation.

Finding Production Gateway URL (endpoint): http://svcs.ebay.com/services/search/FindingService

Sandbox Gateway URL (endpoint): http://svcs.sandbox.ebay.com/services/search/FindingService
ShoppingProduction Gateway URL (endpoint): http://open.api.ebay.com/shopping?


HTTP Headers (XML API Only)

To properly route an XML API request to the appropriate destination within eBay, pass the following information in the HTTP headers. See Making an API Call for an example of how to do this. (If you're using the SOAP API, .NET SDK, or Java SDK, see SOAP URL Parameters (SOAP API and SDKs Only).)

Table: HTTP Headers for XML API Calls
Name Required? Description
X-EBAY-API-COMPATIBILITY-LEVEL Always The eBay release version that your application supports. See the eBay Schema Versioning Strategy for information about how the version affects the way eBay processes your request.
X-EBAY-API-DEV-NAME Conditionally Your Developer ID (DevId), as registered with the eBay Developers Program. The developer ID is unique to each licensed developer (or company). This value is only required for calls that set up and retrieve a user's authentication token (these calls are: GetSessionID, FetchToken, GetTokenStatus, and RevokeToken). In all other calls, this value is ignored. If you lose your keys you can retrieve them using the View Keys link on your My Account page. Here is the direct link to the Keys page (requires signin): http://developer.ebay.com/DevZone/account/keys.asp
X-EBAY-API-APP-NAME Conditionally Your application ID (AppIAppIdD), as registered with the eBay Developers Program. This value is only required for calls that set up and retrieve a user's authentication token (e.g., FetchToken). In all other calls, this value is ignored. Do not specify this value in AddItem and other calls that list items. The application ID is unique to each application created by the developer. The application ID and certificate ID are issued in pairs. Multiple application/certificate ID pairs can be issued for a single developer ID.
X-EBAY-API-CERT-NAME Conditionally Your certificate ID (CertId), as registered with the eBay Developers Program. This value is only required for calls that set up and retrieve a user's authentication token (e.g., FetchToken). In all other calls, this value is ignored. Do not specify this value in AddItem and other calls that list items. The certificate ID is unique to each application created by the developer.
X-EBAY-API-CALL-NAME Always Canonical name of the call you are using (e.g., AddItem). To be routed correctly, the value must match the request name. For example, if you are using AddItemRequest, specify "AddItem" (without "Request") in this call name header.
X-EBAY-API-SITEID Always eBay site to which you want to send the request. See SiteCodeType for a list of valid site ID values.

This is usually the eBay site an item is listed on or that a user is registered on, depending on the purpose of the call. See Specifying the Target Site to understand how the site ID may affect validation of the call and how it may affect the data that is returned. For calls like AddItem, the site that you pass in the body of the request must be consistent with this header. Note: In AddItem, you specify the 2-letter site code. In this header, you specify the numeric site ID.
Content-Type Recommended Specify "text/xml". Sending any other value might cause the call to fail. Note: If you use a library that sets the ContentType header by default, make sure it uses "text/xml".
Content-Length Recommended The length of the XML request string you are sending. Used by eBay to determine how much data to read from the stream.

SOAP URL Parameters (SOAP API and SDKs Only)

To properly route a SOAP API request to the appropriate destination within eBay, pass the following information in the URL query string.

Table: URL Query String Parameters (SOAP API)
Key Value
appid A set of Sandbox Keys (AppId, DevId, CertId) is issued to you by Developer Relations when you first join the Developers Program. The application ID (AppId) is unique to each application created by the developer. The AppId is only applicable to calls that set up and retrieve a user's authentication token (e.g., FetchToken). In all other calls, this value is ignored. Do not specify this value for AddItem and other calls that list items. In order to retrieve a user's authentication token, you also will need to pass the AppId value in the SOAP envelope (along with your DevId and CertId). As mentioned above, the full set of developer keys is required for GetTokenStatus and RevokeToken API calls. See Security for more information.
version This is the version of the payload schema you are using. The version should match the version you pass in the message body. See Release Versions for details.
callname This is the canonical name of the request (e.g., AddItem). The routing service cannot look within the message body to determine the request type. Therefore, although the message itself will identify the request you're making, this information is also required in the URL.
siteid This is the site that item of interest is (or will be) listed on or (for requests that get/set user information) that the requesting or target user is registered on. See Specifying the Target Site for more information about sending requests to international sites and special sites. See Field Differences for eBay Sites for current site IDs.
Routing Specify Routing=new to direct the call to a single namespace server.

Header recommendations: set Content-Type to "application/soap+xml", and set SOAPAction to "".

Theoretically, the URL resulting from the SOAP request would look something like this (if hard-coded in your application):

https://api.ebay.com/wsapi?callname=AddItem&siteid=0&appid=myappid&version=511&Routing=new

Note: If you use a third-party tool for monitoring or logging message data, the tool may require you to pass the URL into your application in a different manner. Please refer to the tool's documentation for instructions.

The following example applies to the SOAP API and shows one way to specify the routing information. The query arguments are hard-coded here for illustration purposes only. This example is in Java, but the logic would be similar for any programming language.

Example: Specifying Routing Information in the Request URL
// Define the endpoint (e.g., the Sandbox Gateway URI)
String endpoint = "https://api.sandbox.ebay.com/wsapi";
// Define the query string parameters.
String                 queryString = "?callname=AddItem"
                                        + "&siteid=0"
                                        + "&appid=myappid"
                                        + "&version=349";
                                        + "&Routing=new";
String                 requestURL  = endpoint + queryString;
EBayAPIInterfaceServiceLocator  sl = new EBayAPIInterfaceServiceLocator();
EBayAPIInterface       privBinding = sl.geteBayAPI(new URL(requestURL));
((EBayAPISoapBindingStub)privBinding).setTimeout(60000);

Note: The eBay WSDL defines the message signatures along with the service location information. See the eBaySvc.wsdl file for more information. In the WSDL, the message elements define the request and response messages and the data types to use in the body of those messages. The message names are the same as the data type element names (e.g., AddItemRequest). In the portType clause, you'll see the name of the service definition interface (the interface you'll use to access operations) will be derived from eBayAPIInterface. This interface specifies each logical operation (e.g., AddItem) and indicates that they are bidirectional (request-response). In the binding clause, you'll see that the name of the proxy that implements the service definition interface will be derived from eBayAPISoapBinding. The binding indicates that each operation needs to be transmitted using the SOAP document-literal style. In the service clause, you'll see that the name of the service locator in the Production environment will be derived from eBayAPIInterfaceService. The service locator specifies the physical location of the service endpoint (i.e., the URI of the service provider—eBay's Production SOAP API gateway). You will need to override this value when executing calls in the Sandbox. It is therefore a good idea to set the endpoint yourself in general, rather than obtaining it from the service locator.

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.