Responses

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 requests to the Web Services web server and then process the responses that are returned. Responses in Web Services are constructed in XML format using the SOAP protocol. This page provides information about the format of the Web Services response.

Introduction

A Web Services SOAP response that is returned by the Web Services server contains an Envelope element with a Header element and a Body element:

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

      <soap:Header>
         ...
      </soap:Header>

      <soap:Body>
         ...
      </soap:Body>

   </soap:Envelope>

The header contains transaction information about the request, regardless of whether the request succeeded or failed. If the request was successful, the body will contain either the return elements and data, or the empty string (for those operations that do not return data). If the request was not successful, the body will contain an error code and error message.

Response SOAP Header

The SOAP header in the response contains elements that provide information about the response, the command group, and your quota:

  • remainingQuota: The quota remaining for the command group.
  • quotaUsedForThisRequest: The quota deducted for this request. If a system error occurs during the request, no quota is deducted.
  • commandGroup: The command group to which the operation belongs.
  • timeTakenMillis: How long the operation took to complete inside the service backend (excluding network latency).
    <?xml version='1.0' encoding='UTF-8'?>
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://apt.yahooapis.com/V2">

    <soap:Header>
        <remainingQuota>9999974</remainingQuota>
        <quotaUsedForThisRequest>532</quotaUsedForThisRequest>
        <commandGroup>Creatives</commandGroup>
        <timeTakenMillis>2813</timeTakenMillis>
    </soap:Header>

    <soap:Body>
        ...
    </soap:Body>

</soap:Envelope>

Tracking Quota

Your Web Services license 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 (see Request SOAP Body). Each Web Services response includes four elements in the SOAP header; use the remainingQuota and commandGroup elements to track your quota consumption.

Response SOAP Body

The SOAP body in the response contains the response elements and data. For example, the response for the SiteService getSites operation might look like this:

   <?xml  version="1.0" encoding="UTF-8"?>
   <soap:Envelope  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"  
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

      <soap:Header>
         ...
      </soap:Header>

      <soap:Body>
         <getSitesResponse  xmlns="http://apt.yahooapis.com/V2/"> 
            <out  xmlns="http://apt.yahooapis.com/V2/">
               <Site>
                  <ID>12975501</ID>
                  <accountID>22057604974</accountID>
                  <createTimestamp>2008-06-02T14:30:07.107-04:00</createTimestamp>
                  <description>Sports Main Page</description>
                  <language>en_US</language>
                  <lastUpdateTimestamp>2008-06-02T14:30:07.107-04:00</lastUpdateTimestamp>
                  <name>Web Services Example Sports Page</name>
                  <status>Inactive</status>
                  <url>http://www.sports.com</url>
               </Site>
               <Site>
                  <ID>12980501</ID>
                  <accountID>22057604974</accountID>
                  <createTimestamp>2008-06-02T14:31:57.178-04:00</createTimestamp>
                  <description>Finance Page</description>
                  <language>en_US</language>
                  <lastUpdateTimestamp>2008-06-02T14:31:57.178-04:00</lastUpdateTimestamp>
                  <name>Web Services Example Finance Page</name>
                  <status>Inactive</status>
                  <url>http://www.finance.com</url>
               </Site>
               <Site>
                  <ID>12981001</ID>
                  <accountID>22057604974</accountID>
                  <createTimestamp>2008-06-02T14:32:02.267-04:00</createTimestamp>
                  <description>Food Recipes Main Page</description>
                  <language>en_US</language>
                  <lastUpdateTimestamp>2008-06-02T14:32:02.267-04:00</lastUpdateTimestamp>
                  <name>Web Services Example Food Recipes Page</name>
                  <status>Inactive</status>
                  <url>http://www.foodrecipes.com</url>
               </Site>
            </out>
         </getSitesResponse>
      </soap:Body>

   </soap:Envelope>

To capture errors for individual objects, some operations have responses that contain error elements as part of the response data. This is particularly useful for list-based operations that include multiple objects. (For example, see the SiteResponse data object.) Given this, the response for the SiteService addSites operation might look like this:

   <soap:Envelope  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

      <soap:Header>
         ...
      </soap:Header>

      <soap:Body>
         <addSitesResponse xmlns="http://amp.yahooapis.com/@versionSuffic@/">
            <out xmlns="http://apt.yahooapis.com/V2/">
               <SiteResponse>
                  <errors xsi:nil="true"  />
                  <operationSucceeded>true</operationSucceeded>
                  <site>
                     <ID>12975501</ID>
                     <accountID>22057604974</accountID>
                     <createTimestamp>2008-06-02T14:30:07.107-04:00</createTimestamp>
                     <description>Sports Main Page</description>
                     <language>en_US</language>
                     <lastUpdateTimestamp>2008-06-02T14:30:07.107-04:00</lastUpdateTimestamp>
                     <name>Web Services Example Sports Page</name>
                     <status>Inactive</status>
                     <url>http://www.sports.com</url>
                  </site>
               </SiteResponse>
               <SiteResponse>
                  ....
               </SiteResponse>
            </out>
         </addSitesResponse>
      </soap:Body>

   </soap:Envelope>

List-Based Operations

List-based operations allow you to operate on multiple objects via the same request. When you set up a list-based operation, you list the objects in a specific order. The operation's response will maintain this order when the response objects are returned (see List-Based Operations for Web Services Requests).

This is particularly important when you are working with add operations, such as addSites or addRateCards, which do not include the IDs as identifiers (because the objects have not yet been created).

For example, suppose you use the addRateCards operation to create three new rate cards and, one of these rate cards has an error in it. Since the operation's response will maintain your ordering, you can easily identify which rate card has the error: if the second rate card contains the error, then the second response object indicates that the operation failed (operationSucceeded = false).

Lists of Elements

Lists of elements in the response are enclosed by a single element. For example, getSites, which returns a list of Site elements, has a response body like this:

   <?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Header> .... </soap:Header> <soap:Body> <getSitesResponse xmlns="http://apt.yahooapis.com/V2/"> <out xmlns="http://apt.yahooapis.com/V2/"> <Site> ... </Site> <Site> ... </Site> <Site> ... </Site> </out> </getSitesResponse> </soap:Body> </soap:Envelope>

Errors and Exceptions

If your SOAP request is successful, the Web Services web server will return an HTTP 200 OK response code and the SOAP response as described above.

If an error or exception occurs during the processing of your SOAP request, the Web Services web server will return an error code and a message. The body will contain a Fault element, which consists of a faultcode element, a faultstring element, and a detail element:

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

      <soap:Body>
         <soap:Fault>
            <faultcode>soap:Client</faultcode>
            <faultstring>Quota exceeded</faultstring>
            <detail>
               <yns:ApiFault>
                  <yns:code>E1015</yns:code>
                  <yns:message>Quota exceeded</yns:message>
               </yns:ApiFault>
            </detail>
         </soap:Fault>
      </soap:Body>

   </soap:Envelope>

See SOAP Faults for a list of Web Services fault codes and error messages.

Complete Example

This example shows a complete SOAP response for adding sites.

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

      <soap:Header>
         <remainingQuota>9999915</remainingQuota>
         <quotaUsedForThisRequest>1</quotaUsedForThisRequest>
         <commandGroup>Marketing<commandGroup>
         <timeTakenMillis>8879<timeTakenMillis>
      </soap:Header>

      <soap:Body>
         <addSitesResponse  xmlns="http://apt.yahooapis.com/V2">
            <out  xmlns="http://apt.yahooapis.com/V2">
               <SiteResponse><errors xsi:nil="true"  />
                  <operationSucceeded>true</operationSucceeded>
                  <site><ID>12975501</ID>
                     <accountID>22057604974</accountID>
                     <createTimestamp>2008-06-02T14:30:07.107-04:00</createTimestamp>
                     <description>Sports Main Page</description>
                     <language>en_US</language>
                     <lastUpdateTimestamp>2008-06-02T14:30:07.107-04:00</lastUpdateTimestamp>
                     <name>Web Services Example Sports Page</name>
                     <status>Inactive</status>
                     <url>http://www.sports.com</url>
                  </site>
               </SiteResponse>
               <SiteResponse>
                  <errors xsi:nil="true"  />
                  <operationSucceeded>true</operationSucceeded>
                  <site>
                     <ID>12976001</ID>
                     <accountID>22057604974</accountID>
                     <createTimestamp>2008-06-02T14:30:11.564-04:00</createTimestamp>
                     <description>Food Recipes Main Page</description>
                     <language>en_US</language>
                     <lastUpdateTimestamp>2008-06-02T14:30:11.564-04:00</lastUpdateTimestamp>
                     <name>Web Services Example Food Recipes Page</name>
                     <status>Inactive</status>
                     <url>http://www.foodrecipes.com</url>
                  </site>
               </SiteResponse>
            </out>
         </addSitesResponse>
      </soap:Body>

   </soap:Envelope>


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