Skip to search.

Breaking News Visit Yahoo! News for the latest.

×Close this window

APT from Yahoo! Web Services > APT from Yahoo! Web Services Version 15.0.0 > Getting Started Guide

Requests

Last Updated: May 09, 2013
Text Size: A A A

Save to My Help

Save this article to My Help for easy reference. You can visit the article at any time from any computer.

Replace an article

You have reached the maximum number of saved articles. Your oldest saved article will be replaced with the new one.

To use Web Services, make service requests to the Web Services web server and then process the responses that are returned. Requests in Web Services are constructed in XML format using the SOAP protocol. This page provides information about constructing Web Services requests.

Introduction

A Web Services SOAP request contains an Envelope element with a Header element and a Body element. 

   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
         ...
      </soapenv:Header>

      <soapenv:Body>
         ...
      </soapenv:Body>

   </soapenv:Envelope>

To create a Web Services request, first choose the service and operation. Then create the SOAP header and the SOAP body. The next three sections will walk you through this process.

Web Services

To create a Web Services request, the first step is to choose the service and operation.

The services are described in the Service Overviews. Each service defines a number of operations. You may include exactly one operation in each request, as explained in the API Reference.

To build the request, you will need to know the name of the service (for example, SiteService), the name of the operation (for example, addSite), and the parameters that define the operation (for example, site). As you build your request, keep in mind that the names of services, operations, data objects, elements, and constants are case sensitive.

Note: Restrictions apply to all elements. If a required element is missing from any data object that is a part of an operation, the entire request is considered invalid and the operation will fail. This applies to operations with one object (for example, addSite) as well as list-based operations that include multiple objects (for example, addSites).

Request SOAP Header

After you have selected the service and operation, the second step is to create the SOAP header.

The SOAP header contains metadata about the request, such as authentication information. The SOAP header must include these elements:

Element Description Required
username Your username Yes
password Your password Yes
license Your license key Yes
accountID Your account ID or the account ID of the managed account Yes

Username and Password

The username and password can be defined in the header in one of two ways:

  • With the UsernameToken element of the WS-Security web services extension.
  • With the username and password elements if your SOAP toolkit does not support WS-Security.

The preferred method is through the WS-Security extension, where both the Username and Password elements are wrapped in the Security and UsernameToken elements, as shown below. To use WS-Security you must also include the secext schema in the SOAP envelope (here defined as wsse): 

   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
         <wsse:Security>
           <wsse:UsernameToken>
             <wsse:Username>user</wsse:Username>
             <wsse:Password>password</wsse:Password>
           </wsse:UsernameToken>
         </wsse:Security>
         ...      
      </soapenv:Header>

      <soapenv:Body>
         ...
      </soapenv:Body>

   </soapenv:Envelope>

If your SOAP toolkit does not support WS-Security, use the username and password elements in the header: 

   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
 	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
        <username>user</username>
        <password>password</password>
        ...
      </soapenv:Header>

      <soapenv:Body>
         ...
      </soapenv:Body>

   </soapenv:Envelope>

License Key and Account ID

If you are making the request for your own account, specify your license key and your account ID. If you are making the request for a managed account, specify your license key and the account ID of the managed account. The license and accountID elements are specified in the SOAP header, outside the Security element (if used). 

   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
         <wsse:Security>
           <wsse:UsernameToken>
             <wsse:Username>user</wsse:Username>
             <wsse:Password>password</wsse:Password>
           </wsse:UsernameToken>
         </wsse:Security>
         <license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
         <accountID>9901673</accountID>     
      </soapenv:Header>

      <soapenv:Body>
         ...
      </soapenv:Body>

   </soapenv:Envelope>

Request SOAP Body

After you have defined the SOAP header, the third step is to create the SOAP body.

The SOAP body contains the service operation and its parameters. The service, itself, is declared when you post the request (see Web Services Locations and Requests and HTTP). Only one operation is allowed per request. Parameters must be specified in order.

For example, for the SiteService, the getSites operation takes a list of siteID elements as parameters. The parameter name is siteIDs and the data type is long. The parameter list for this operation looks like this:

   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope 
   	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
         ...
      </soapenv:Header>

      <soapenv:Body>
         <getSites>
           <siteIDs>
             <long>5354501</long>
             <long>5355001</long>
           </siteIDs>
         </getSites>
      </soapenv:Body>

   </soapenv:Envelope>

Tracking Quota

Your license for Web Services specifies your command groups and quota (see Command Groups and Quota). Each Web Services request includes either an operation or list-based operation that counts against your quota. Each Web Services response includes elements in the SOAP header that you can use to track your quota consumption (see Tracking Quota for Web Services Responses).

List-Based Operations

List-based operations allow you to operate on multiple objects in the same request. The objects can be simple data types or complex data types.

When you set up a list-based operation, you list the objects in a specific order. The Web Services operation's response will maintain this order when the response objects are returned (see List-Based Operations for Web Services Responses).

List-based "add" operations, such as addSites, may allow you to add up to 1,000 new objects in a single operation. However, the actual number of objects you can declare per operation is determined by the account configuration. Please contact the account management team for more information about the number of objects (such as sites, ads, folders) that are allowed for the accounts.

Simple Data Types

To indicate a list of simple data types (long, int, string), use an enclosing element named for the parameter. Then enclose each individual parameter in an element named for the data type itself. 

   
   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope   
   	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
         ...
      </soapenv:Header>

      <soapenv:Body>
         <getSites>
            <siteIDs>
               <long>5354501</long>
               <long>5355001</long>
            </siteIDs>
         </getSites>
      </soapenv:Body>

   </soapenv:Envelope>

Complex Data Types

To indicate a list of complex data types (Site, Account, Folder, and so on), use an enclosing element named for the parameter, and then include each data type as its own element (with subelements).

For example, for the SiteService, the addSites operation takes a list of Site elements as parameters. In this case, the parameter name is sites and the data type is Site. The parameter list looks like this:

   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope   
   	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2">

      <soapenv:Header>
         ...
      </soapenv:Header>

      <soapenv:Body>
         <addSites>
            <sites>
               <Site>
                  ...
                  <name>Food Site</name>
                  <description>Description of the site.</description>
                  <url>http://www.exampleurlforfoodsite.com</url>
                  ...
               </Site>
               <Site>
                  ...
                  <name>Finance Site</name>
                  <description>Description of the site.</description>
                  <url>http://www.exampleurloffinancesite.com</url>
                  ...
               </Site>
            </sites>
         </addSites>
      </soapenv:Body>

   </soapenv:Envelope>

Complete Example

A complete example of a SOAP request for the SiteService is shown here. See Web Services Locations and Requests and HTTP for more information about how to send the request to Web Services. 

   
   <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope   
   	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://apt.yahooapis.com/V2"

      <soapenv:Header>
         <wsse:Security>
            <wsse:UsernameToken>
               <wsse:Username>user</wsse:Username>
               <wsse:Password>password</wsse:Password>
            </wsse:UsernameToken>
         </wsse:Security>
         <license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
         <accountID>9901673</accountID>
      </soapenv:Header>

      <soapenv:Body>
         <getSites>
            <siteIDs>
               <long>5354501</long>
               <long>5355001</long>
            </siteIDs>
         </getSites>
      </soapenv:Body>

   </soapenv:Envelope>
Save to My Help
Display in new window

Was this information helpful?      

My Help

Forgot your ID or password?

Sign In

Sign in to see your account information saved articles and more.

  1. Recent Searches (0)

  2. Saved Articles