<?xml version="1.0"?>
<!--
The contents of this file are subject to the terms
of the Common Development and Distribution License
(the "License").  You may not use this file except
in compliance with the License.

You can obtain a copy of the license at
http://www.opensource.org/licenses/cddl1.php
See the License for the specific language governing
permissions and limitations under the License.
-->
<application xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:yn="urn:yahoo:yn"
             xmlns:ya="urn:yahoo:api"
             xmlns:html="http://www.w3.org/1999/xhtml"
             xmlns="http://research.sun.com/wadl/2006/10">

  <grammars>
    <include href="NewsSearchResponse.xsd"/>
    <include href="NewsSearchError.xsd"/>
  </grammars>
  
  <resources base="http://api.search.yahoo.com/NewsSearchService/V1/">
    <resource path="newsSearch">
      <doc xml:lang="en" title="Yahoo News Search Service">
        The <html:i>Yahoo News Search</html:i> service provides online searching of news
        stories from around the world.
      </doc>
      <param name="appid" type="xsd:string" required="true" style="query">
        <doc>The application ID. See <html:a href="http://developer.yahoo.com/faq/index.html#appid">Application IDs</html:a> for more information.</doc>
      </param>
      <method href="#search"/>
    </resource>
  </resources>
  
  <method name="GET" id="search">
    <doc xml:lang="en" title="Search news stories by keyword"/>
    <request>
      <param name="query" type="xsd:string" required="true" style="query">
        <doc xml:lang="en" title="Space separated keywords to search for"/>
      </param>
      <param name="type" type="xsd:string" default="all" style="query">
        <doc xml:lang="en" title="Keyword matching"/>
        <option value="all">
          <doc>All query terms.</doc>
        </option>
        <option value="any">
          <doc>Any query terms.</doc>
        </option>
        <option value="phrase">
          <doc>Query terms as a phrase.</doc>
        </option>
      </param>
      <param name="results" type="xsd:int" default="10" style="query">
        <doc xml:lang="en" title="Number of results"/>
      </param>
      <param name="start" type="xsd:int" default="1" style="query">
        <doc xml:lang="en" title="Index of first result"/>
      </param>
      <param name="sort" type="xsd:string" default="rank" style="query">
        <doc xml:lang="en" title="Sort by date or rank"/>
        <option value="rank"/>
        <option value="date"/>
      </param>
      <param name="language" type="xsd:string" style="query">
        <doc xml:lang="en" title="Language filter, omit for any language"/>
      </param>
      <param name="output" type="xsd:string" default="xml" style="query">
        <doc>The format for the output. If <html:em>json</html:em> is requested, the results will be returned in <html:a href="http://developer.yahoo.com/common/json.html">JSON</html:a> format. If <html:em>php</html:em> is requested, the results will be returned in <html:a href="http://developer.yahoo.com/common/phpserial.html">Serialized PHP</html:a> format.</doc>
        <option value="xml"/>
        <option value="json"/>
        <option value="php"/>
      </param>
      <param name="callback" type="xsd:string" style="query">
        <doc>The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the <html:a href="http://developer.yahoo.com/common/json.html#callbackparam">Yahoo! Developer Network JSON Documentation</html:a>.</doc>
      </param>
    </request>
    <response>
      <representation mediaType="application/xml" element="yn:ResultSet">
        <doc xml:lang="en" title="A list of news items matching the query"/>
      </representation>
      <fault id="SearchError" status="400" mediaType="application/xml"
             element="ya:Error"/>
    </response>
  </method>
  
</application>
