docs: Revised page to include info about new Publisher API.

Also moved the blurb to the "Google Play Distribution" cover page, and
adjusted the TOC accordingly. Per DDoughterty@ 's request, moved the
"Purchase Verification Strategies" section to billing_subscriptions.jd

Page is staged to:

http://asolovay.mtv:9543/google/play/billing/gp-purchase-status-api.html
http://asolovay.mtv:9543/google/play/billing/billing_subscriptions.html#strategies

Change-Id: I884e2f3f25c76fcb055e663058d1a4f4642fb558

5 files changed, 199 insertions, 104 deletions

diff --git a/docs/html/google/google_toc.cs b/docs/html/google/google_toc.cs
index b770135..7cce86b 100644
--- a/docs/html/google/google_toc.cs
+++ b/docs/html/google/google_toc.cs
@@ -138,9 +138,6 @@
       <li><a href="<?cs var:toroot?>google/play/billing/billing_admin.html">
               <span class="en">Administering In-app Billing</span></a>
       </li>
-      <li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">
-              <span class="en">Purchase Status API</span></a>
-      </li>
       <li><a href="<?cs var:toroot?>google/play/billing/versions.html">
               <span class="en">Version Notes</span></a>
       </li>
@@ -205,7 +202,9 @@
       <li><a href="<?cs var:toroot ?>google/play/filters.html">
           <span class="en">Filters on Google Play</span></a>
       </li>
-
+      <li><a href="<?cs var:toroot?>google/play/billing/gp-purchase-status-api.html">
+              <span class="en">Google Play Developer API</span></a>
+      </li>
       <li><a href="<?cs var:toroot ?>google/play/publishing/multiple-apks.html">
           <span class="en">Multiple APK Support</span></a>
       </li>
diff --git a/docs/html/google/play/billing/billing_subscriptions.jd b/docs/html/google/play/billing/billing_subscriptions.jd
index d0e6dc5..3c72da1 100644
--- a/docs/html/google/play/billing/billing_subscriptions.jd
+++ b/docs/html/google/play/billing/billing_subscriptions.jd
@@ -24,6 +24,7 @@ directly from Google Play.</li>
     <li><a href="#administering">Configuring Subscriptions Items</a></li>
     <li><a href="#cancellation">Cancellation</a></li>
     <li><a href="#payment">Payment Processing</a></li>
+    <li><a href="#strategies">Purchase Verification Strategies</a></li>
   </ol>
   <h2>See also</h2>
   <ol>
@@ -325,6 +326,21 @@ each recurring transaction by appending an integer as follows: </p>
 {@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) 
 or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p>
 
+<h2 id="strategies">Purchase Verification Strategies</h2>
+
+<p>In a typical scenario, your app verifies the order status for new purchases
+to ensure that they are valid before granting access to the purchased
+content.</p>
+
+<p>To verify a purchase, the app passes the purchase token and other details up
+to your backend servers, which verifies them directly with Google Play using the
+Purchase Status API.  If the backend server determines that the purchase is
+valid, it notifies the app and grants access to the content.</p>
+
+<p>Keep in mind that users will want the ability to use your app at any time,
+including when there may be no network connection available. Make sure that your
+approach to purchase verification accounts for the offline use-case.</p>
+
 <h2 id="play-dev-api">Google Play Android Developer API</h2>
 
 <p>Google Play offers an HTTP-based API that lets you remotely query the
@@ -333,4 +349,4 @@ API is designed to be used from your backend servers as a way of securely
 managing subscriptions, as well as extending and integrating subscriptions with
 other services.</p>
 
-<p>For complete information, see <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>.</p>
\ No newline at end of file
+<p>For complete information, see <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a>.</p>
diff --git a/docs/html/google/play/billing/gp-purchase-status-api.jd b/docs/html/google/play/billing/gp-purchase-status-api.jd
index 4cfacee..23a4e61 100644
--- a/docs/html/google/play/billing/gp-purchase-status-api.jd
+++ b/docs/html/google/play/billing/gp-purchase-status-api.jd
@@ -1,38 +1,113 @@
-page.title=Purchase Status API
-page.tags="In-app Billing", "Google Play", "inapp billing", "in app billing", "iab", "billing"
+page.title=Google Play Developer API
+page.tags="In-app Billing", "Google Play", "inapp billing", "in app billing", "iab", "billing", "publishing"
 
 @jd:body
 
 <div id="qv-wrapper">
 <div id="qv">
   <h2>In this document</h2>
+  <!-- TODO: Update TOC -->
   <ol>
-    <li><a href="#overview">Overview</a></li>
-    <li><a href="#using">Using the API</a></li>
-        <li><a href="#strategies">Verification Strategies</a></li>
-            <li><a href="#practices">Using the API Efficiently</a></li>
+    <li><a href="#publishing_api_overview">Publishing API</a>
+    <li><a href="#subscriptions_api_overview">Subscriptions and In-App
+          Purchases API</a></li>
+    <li><a href="#using">Using the API</a>
+    <li><a href="#edits">Staged Edits</a></li>
+    <li><a href="#practices">Using the API Efficiently</a>
+      <ol>
+        <li><a href="#quota">Quota</a></li>
+      </ol>
+    </li>
   </ol>
+
   <h2>See also</h2>
   <ol>
-    <li><a href="https://developers.google.com/android-publisher/v1_1/">Google Play Android Developer API</a></li>
+    <li><a href="https://developers.google.com/android-publisher/">Google Play
+        Developer API</a> documentation</li>
+    <li><a href="https://support.google.com/googleplay/android-developer/answer/6071616">Google
+        Help Center</a> overview of the Google Play Developer API</li>
   </ol>
 </div>
 </div>
 
-<p>Google Play provides an HTTP-based Purchase Status API that lets
-you remotely query the status of a specific in-app product or subscription,
-or cancel an active subscription. The API is designed to be used from your
-backend servers as a way of securely managing in-app products and
-subscriptions, as well as extending and integrating them with other services.</p>
+<p>The Google Play Developer API is a REST-based web service that allows you to perform publishing
+and app-management tasks. You can use this API to integrate your publishing
+operations with your release-management process.</p>
+
+<p>Not all developers will need to use these APIs&mdash;in most cases you will
+continue to manage your apps directly using the Google Play Developer Console.
+However, if you have a large number of APKs to manage, or have to track user
+purchases and subscriptions, you may find this API very useful.</p>
+
+<p>Using the Google Play Developer API, you can automate a variety of
+app-management tasks, including:</p>
+
+<ul>
+<li>Uploading and releasing new versions of your app</li>
+<li>Editing your app Google Play Store listings, including localized text and
+    graphics</li>
+<li>Managing your in-app product catalog, your products purchase status and your
+    app subscriptions</li>
+</li>
+</ul>
+
 
-<h2 id="overview">Overview</h2>
 
-<p>With the Purchase Status API you can quickly retrieve the details of any
-purchase using a standard GET request. In the request you supply information
-about the purchase &mdash; app package name, purchase or subscription ID,
-and the purchase token. The server responds with a JSON object describing
-the associated purchase details, order status, developer payload, and other
-information.</p>
+<p>The Google Play Developer API lets you focus on designing and developing your
+app, while spending less time and effort managing your releases, even as you
+grow to new markets.</p>
+
+<p>The Google Play Developer API includes two components:</p>
+
+<ul>
+<li>The <a href="#publishing_api_overview">Publishing API</a> lets you upload and publish
+  apps, and perform other publishing-related tasks.</li>
+<li>The <a href="#subscriptions_api_overview">Subscriptions and In-App Purchases
+  API</a> lets you manage in-app purchases and subscriptions. (This was
+  previously known as the "Purchase Status API".)</li>
+</ul>
+
+<h2 id="publishing_api_overview">Publishing API</h2>
+
+<p>
+The Google Play Developer Publishing API allows you to automate frequent tasks
+having to do with app distribution. This provides functions
+similar to those available to a developer through the Google Play
+Developer Console, such
+as:
+</p>
+
+<ul><li>Uploading new versions of an app</li>
+<li>Releasing apps, by assigning APKs to various <em>Tracks</em> (alpha, beta,
+  staged rollout, or production)</li>
+<li>Creating and modifying Google Play Store listings, including localized text
+  and graphics and multi-device screenshots</li></ul>
+
+<p>Those tasks are performed using the
+<a href="#edits">edits</a>
+functionality, which takes a transactional approach to making changes &mdash;
+you bundle several changes into a single draft edit, then commit the changes all
+at once. (None of the changes take effect until the edit is committed.)</p>
+
+<p class="note"><strong>Note:</strong> Not all developers will need to use this
+API. All the functionality provided by the API is also available through the
+Google Play
+Developer Console. However, this API lets you integrate your app and listing
+update process with your existing tools, which will be very useful for some
+developers. In particular, if you have a large number of APKs to manage, or
+localized listings in many different locales, you may find this API invaluable.
+</p>
+
+<h2 id="subscriptions_api_overview">Subscriptions and In-App Purchases API</h2>
+
+<p>The API allows you to manage your app's catalog of in-app products and
+subscriptions. In addition, with the Subscriptions and In-App Purchases API you
+can quickly retrieve the
+details of any purchase using a standard GET request. In the request you supply
+information about the purchase &mdash; app package name, purchase or
+subscription ID, and the purchase token. The server responds with a JSON object
+describing the associated purchase details, order status, developer payload, and
+other information.</p>
 
 <p>You can use the Purchase Status API in several ways, such as for reporting
 and reconciliation of individual orders and for verifying purchases and
@@ -40,101 +115,85 @@ subscription expirations. You can also use the API to learn about cancelled
 orders and confirm whether in-app products have been consumed, including
 whether they were consumed before being cancelled.</p>
 
-<p>For subscriptions, in addition to querying for order status and expiration,
-you can use the Purchase Status API to remotely cancel a subscription. This is a
-convenient way to manage cancellations on behalf of customers, without
-requiring them to manage the cancellation themselves on their Android devices.</p>
-
-<p>If you plan to use the Purchase Status API, keep in mind that:</p>
-<ul><li>You can use the API to check the status of individual items only
-&mdash; bulk requests for order status are not supported at this time.</li>
-<li>You can query for the details of orders placed on or after 12 June 2013,
-but not for orders placed earlier.</li>
-<li>You can query purchases of any item type made with the In-app
-Billing v3 API, or purchases of managed items made with In-app Billing v1 and
-v2. You can not use the Purchase Status API to query purchases of unmanaged items
-made with In-app Billing v1 or v2.</li>
-</ul>
+<p class="note"><strong>Note:</strong> The Subscriptions and In-App
+Purchases API does not use the new, transactional "edits" functionality used by
+the <a href="#publishing_api_overview">Publishing API</a>. Methods for the
+<a href="https://developers.google.com/android-publisher/api-ref/inappproducts">Inappproducts</a>,
+<a href="https://developers.google.com/android-publisher/api-ref/purchases/products">Purchases.products</a>,
+and <a href="https://developers.google.com/android-publisher/api-ref/purchases/subscriptions">Purchases.subscriptions</a>
+resources take effect immediately. Each resource's API reference page notes
+specifically whether the methods for that resource use the "edits"
+model.</p>
 
 <p>The Purchase Status API is part of the <a
-href="https://developers.google.com/android-publisher/v1_1/">Google Play Android
-Developer API v1.1</a>, available through the Google Developers Console. The new version
-of the API supersedes the v1 API, which is deprecated. If you are using the v1
-API, please migrate your operations to the v1.1 API as soon as possible.</p>
-
+href="https://developers.google.com/android-publisher/">Google Play Developer
+API</a> v. 2.0, available through the Google Developers Console.</p>
 
 <h2 id="using">Using the API</h2>
 
-<p>To use the API, you must first register a project at the <a
-href="https://cloud.google.com/console">Google Developers Console</a> and receive
-a Client ID and shared secret that  your app will present when calling the
-API. All calls are authenticated with OAuth 2.0.</p>
+<p>To start making API calls, you’ll set up and manage the Google Play Developer
+API directly from the <a href="https://play.google.com/apps/publish/">Google
+Play Developer Console</a>. The API can only be managed by the owner of your
+Google Play Developer account.</p>
 
-<p>Once your app is registered, you can access the API directly, using standard
-HTTP methods to retrieve and manipulate resources. The API is built on a RESTful
-design that uses HTTP and JSON. so any standard web stack can send requests and
-parse the responses. However, if you don’t want to send HTTP requests and parse
-responses manually, you can access the API using the Google APIs Client
-Libraries, which provide better language integration, improved security,
-and support for making calls that require user authorization.</p>
+<p>To access the API, you'll need to:</p>
 
-<p>For more information about the API and how to access it through the Google
-APIs Client Libraries, see the documentation at:</p> 
-
-<p style="margin-left:1.5em;"><a
-href="https://developers.google.com/android-publisher/v1_1/">https://developers.
-google.com/android-publisher/v1_1/</a></p>
-
-<h3 id="quota">Quota</h3>
-
-<p>Applications using the Google Play Android Developer API are limited to an
-initial courtesy usage quota of <strong>200,000 requests per day</strong> (per
-application). This should provide enough access for normal
-subscription-validation needs, assuming that you follow the recommendation in
-this section.</p>
-
-<p>If you need to request a higher limit for your application, see the
-instructions in the <a
-href="https://developers.google.com/console/help/new/#trafficcontrols">Google Developers
-Console Help</a>.
-Also, please read the section below on design best practices for minimizing your
-use of the API.</p>
+<ol><li>Set up a new or existing API project</li>
+<li>Set up one or more authorized clients, which can be either:
+<ul>
+  <li><a href="https://developers.google.com/accounts/docs/OAuth2">OAuth
+      clients</a></li>
+  <li><a href="https://developers.google.com/accounts/docs/OAuth2ServiceAccount">
+      service account</a></li>
+</ul></li></ol>
 
-<h3 id="auth">Authorization</h3>
+<p>For full details, see the Google Play Developer API
+<a href="https://developers.google.com/android-publisher/getting_started">Getting
+Started</a> page.</p>
 
-<p>Calls to the Google Play Android Developer API require authorization. Google
-uses the OAuth 2.0 protocol to allow authorized applications to access user
-data. To learn more, see <a
-href="https://developers.google.com/android-publisher/authorization">Authorization</a>
-in the Google Play Android Developer API documentation.</p>
+<h2 id="edits">Staged Edits</h2>
 
-<h2 id="strategies">Purchase Verification Strategies</h2>
+<p>The Google Play Developer Publishing API Edits methods allow you to prepare
+and commit changes to your Google Play apps. Once your update is ready to go,
+you can deploy it with a single operation. The changes you can make include:</p>
 
-<p>In a typical scenario, your app verifies the order status for new purchases
-to ensure that they are valid before granting access to the purchased content.</p>
+<ul>
+  <li>Uploading one or more APKs</li>
+  <li>Assigning different APKs to different “tracks”: alpha, beta, staged
+      rollout, and production</li>
+  <li>Creating and modifying localized store listings for the app</li>
+  <li>Uploading screenshots and other images for the app’s store listings</li>
+</ul>
 
-<p>To verify a purchase, the app passes the purchase token and other details up
-to your backend servers, which verifies them directly with Google Play using the
-Purchase Status API. For security reasons, the app should not normally attempt to verify
-the purchase itself using the Purchase Status API.</p>
+<p>Once all the desired changes have been staged, they are all committed with a
+single operation.</p>
 
-<p>If the backend server determines that the purchase is valid, it notifies the
-app and grants access to the content. For improved performance, the backend servers
-should store the purchase details and order status in a local database, updated at
-intervals or as-needed.</p>
+<p>For full details on staged edits, see the Google Play Developer API
+<a href="https://developers.google.com/android-publisher/edits/">Edits</a>
+page.</p>
 
-<p>Keep in mind that users will want the ability to use your app at any time, including
-when there may be no network connection available. Make sure that your approach to
-purchase verification accounts for the offline use-case.</p>
+<p class="note"><strong>Note:</strong> The new, transactional "edits"
+functionality is only used by the <a href="#publishing_api_overview">Publishing
+API</a>. Methods for the <a href="#subscriptions_api_overview">Subscriptions and
+In-App Purchases API</a> take effect immediately. Each resource's API reference
+page notes specifically whether the methods for that resource use the "edits"
+model.</p>
 
 <h2 id="practices">Using the API Efficiently</h2>
 
-<p>Access to the Google Play Android Developer API is regulated to help ensure a
-high-performance environment for all applications that use it. While you can
+<p>Access to the Google Play Developer API is regulated to help ensure a
+high-performance environment for all applications that use it (as described in
+<a href="#quota">Quota</a>). While you can
 request a higher daily quota for your application, we highly recommend that you
-minimize your access using the techniques below. </p>
+minimize your access using these techniques: </p>
 
 <ul>
+  <li><em>Limit the number of app updates</em> &mdash; Do not publish alpha or beta
+  updates more frequently than once a day. (Production apps should be updated
+  even less frequently than that.) Every update costs your users time and
+  possibly money. If you update too frequently, users will start ignoring
+  updates, or even uninstall the product. (Of course, if there's a major problem
+  with your app, go ahead and fix it.)</li>
   <li><em>Query the Purchase Status API for new purchases only</em> &mdash; At
   purchase, your app can pass the purchase token and other details to your backend
   servers, which can use the Purchase Status API to verify the purchase.</li>
@@ -163,6 +222,15 @@ minimize your access using the techniques below. </p>
 </ul>
 
 <p>By following those general guidelines, your implementation will offer the
-best possible performance for users and minimize use of the <a
-href="https://developers.google.com/android-publisher/v1_1/">Google Play Android
-Developer API</a>.</p>
+best possible performance for users.</p>
+
+<h3 id="quota">Quota</h3>
+
+<p>Applications using the Google Play Developer API are limited to an
+initial courtesy usage quota of <strong>200,000 requests per day</strong> (per
+application). This should provide enough access for publishing activities and
+normal subscription-validation needs.</p>
+
+<p>If you need to request a higher limit for your application, use the "Request
+more" link on the <strong>Quotas</strong>
+pane of the Google Developers Console.</p>
diff --git a/docs/html/google/play/billing/index.jd b/docs/html/google/play/billing/index.jd
index dce20cb..18b1523 100644
--- a/docs/html/google/play/billing/index.jd
+++ b/docs/html/google/play/billing/index.jd
@@ -14,7 +14,11 @@ and features, and more. You can use In-app Billing to sell products as</p>
 <div class="sidebox">
   <h2><strong>New in In-App Billing</strong></h2>
   <ul>
-  <li><strong>Purchase Status API</strong>&mdash;The <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Purchase Status API</a> lets you query the status of in-app product or subscription purchases. </li>
+  <li><strong>Google Play Developer API</strong>&mdash;The
+    <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google
+    Play Developer API</a> allows you to perform a number of publishing and
+    app-management tasks. It includes the functionality previously known as the
+    <em>Purchase Status API.</em> </li>
   <li><strong>In-app Billing Version 3</strong>&mdash;The <a href="{@docRoot}google/play/billing/api.html">latest version</a> of In-app Billing features a synchronous API that is easier to implement and lets you manage in-app products and subscriptions more effectively.</li>
   <li><strong>Subscriptions now supported in Version 3</strong>&mdash;You can query and launch purchase flows for subscription items using the V3 API.</li>
   <li><strong>Free trials</strong>&mdash;You can now offer users a configurable <a href="/google/play/billing/v2/billing_subscriptions.html#trials">free trial period</a> for your in-app subscriptions. You can set up trials with a simple change in the Developer Console&mdash;no change to your app code is needed.</li>
diff --git a/docs/html/google/play/dist.jd b/docs/html/google/play/dist.jd
index b4efe40..f1ad834 100644
--- a/docs/html/google/play/dist.jd
+++ b/docs/html/google/play/dist.jd
@@ -49,4 +49,12 @@ page.title=Google Play Distribution
     <p>Protect your revenue streams and integrate policies for usage into your app.
     </p><a href="{@docRoot}google/play/licensing/index.html">Learn more &raquo;</a>
   </div>
-</div>
\ No newline at end of file
+  <div class="layout-content-col span-6">
+    <h4>
+      Google Play Developer API
+    </h4>
+    <p>Integrate your publishing operations with your release-management
+      process.
+    </p><a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Learn more &raquo;</a>
+  </div>
+</div>