Merge lp:~ralsina/tanuki-agent/fix-product-ref into lp:tanuki-agent

[Roberto Alsina]

Update doc to the current product-based API (part 1: products/testspecs/baseimages)

Update doc to the current product-based API (part 1: products/testspecs/baseimages)

[Bret Barker (noise)]

LGTM, I can take a stab at the FIXMEs after.

review: Approve

=== modified file 'docs/api-reference-products.md'
--- docs/api-reference-products.md	2015-11-27 12:34:13 +0000
+++ docs/api-reference-products.md	2016-01-04 19:07:00 +0000
@@ -1,5 +1,5 @@
 Title:   Ubuntu Core Product Integration API Guide
-Version: 20151105
+Version: 20160104
 
 [TOC]
 
@@ -14,6 +14,9 @@
     the Product. It is free-form with data of your choosing (e.g. a
     pointer to a binary to be provisioned on the device). Defined either
     via a manifest or advertised to the system on-demand.
+-   **Base Image**: represents a tested configuration, 
+    specifically the combination of snaps that form that configuration. It can be
+    marked as "released", meaning it's in use by end users.
 -   **Test Spec**: defines Tests to be run on
     matching images
 -   **Test Opportunity**: an instance of a
@@ -26,11 +29,11 @@
 ============
 
 All API endpoints are authenticated, which ensures private access
-to your Organization's information.
+to your product's information.
 
 To authenticate properly to the system, you'll first need oauth
 credentials that are obtained via the Agent (see next chapter below,
-“Lab Operation”, under “<span class="c28">[Authentication](#h.u7ke0hug9g6j)”
+"Lab Operation", under "<span class="c28">[Authentication](#h.u7ke0hug9g6j)"
 section).
 
 <!-- LINK TO CORRECT PLACE IN TUTORIAL? -->
@@ -75,11 +78,9 @@
 
 Make a signed request to the Manifest Listing endpoint:
 
-    >>> url = "https://spi.canonical.com/orgs/docs-org/products/manifests"
+    >>> url = "https://spi.canonical.com/products"
     >>> res = authenticated_session.get(url)
 
-
-
 The authenticated\_session will oauth-sign the request, appending
 an HTTP Authorization header that looks like:
 
@@ -93,13 +94,16 @@
     >>> res.status_code
     200
     >>> res.json()
-    {'manifests': [{'base\_image\_reference': 'http://foo.com/bar',
-        'created_at': '2015-08-25T08:00:10.500533',
-        'id': '71e81dbb-4eb5-45df-a813-6e9efe0851be',
-        'image_name': 'docs-img68f9005f7fdb4c07ae322de432f22f26',
-        'release': '15.04',
-        'snaps': [{'locked': True, 'name': 'snap-a', 'revision': 1},
-                  {'locked': False, 'name': 'snap-b', 'revision': None}]}]}
+    {'packages': ['test-snap.foo'],
+    'products': [{'active': True,
+                'created_at': '2016-01-04T16:03:18.721607',
+                'id': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+                'name': 'test-product.foo',
+                'primary_snap_name': 'test-snap.foo',
+                'release': '15.04-core',
+                'snaps': ['pi2.canonical',
+                          'webdm.canonical',
+                          'test-snap.foo']}]}
 
 In order to simplify the examples given in the API references
 throughout this document, we have provided a helper script as part of
@@ -143,71 +147,43 @@
 Product Management
 ------------------
 
-Note: Product Manifests support products built from
-Snaps. If you are instead bootstrapping Product Integration with a pre-existing binary
-image, please skip ahead to the next section - Test Management.
-
-A Product is defined by a Manifest that has an image\_name
-and either a list of snaps that comprise the image (e.g. as specified in
-a Gadget Snap) or a base\_image\_reference.
-
-The image\_name is used to relate Test Specs (see below) to
-Manifests.
-
-Manifests and Test Specs may be deactivated or deleted
-permanently. Even if deleted, details of the Test Spec and Manifest (if
-any) that led to the Test Opportunity are persisted in the Test Result
-data.
-
-
-
-To modify a Test Spec or Manifest, the user should delete the
-existing one and create a new one with the desired changes. That will
-not automatically trigger new tests, for that see [Test Triggering](#test-triggering).
-
-A manifest contains the following fields:
-
--   ```image_name```: a unique name within an
-    organization that is combined with each
+**FIXME ADD EXPLANATIONS** 
+
+A product contains the following fields:
+
+-   ```name```: a unique name for this product that is combined with each
     test case to produce the full set of test
     opportunities. I.e. if you have two test cases with a
-    matching image\_name, then two test opportunities will be created.
+    matching name, then two test opportunities will be created.
     Maximum length is 200 characters.
 -   ```release``` snappy release series, e.g.
-    “15.04”. Maximum length is 200 characters.
--   ```base_image_reference``` is opaque to
-    the system; it is for your Provisioning Kit in your lab to
-    interpret and use. It can be any JSON
-    value. This allows for URLs to actual image binaries,
-    data for on-the-fly image composition, etc. Maximum length is 1000
-    characters.
+    "15.04". Maximum length is 200 characters.
+-   ```primary_snap_name``` name of the snap used to control access to this product.
 -   ```snaps``` list of snaps that make up the
     product. This list will be used to for snappy based products to
     trigger tests when new Snap revisions are made available.
 
-    The format is a list of: ```[snap_name, revision_num, locked]```
-
-    -   ```snap_name``` is the name of the Snap in the Store
-    -   ```revision``` is the revision number (integer) that was used in the base image creation
-    -   ```locked``` is a boolean indicating if that revision should be locked when generating Tests or can float as snaps are updated.
-
 In the current system, interaction is via an HTTP API and detailed below:
 
 <table class="table">
 <tr>
-    <th> Action     <th>Manifest Creation
+    <th> Action     <th>Product Creation
 <tr>
-    <td>URL         <td>https://spi.canonical.com/orgs/<org-id\>/products/manifests
+    <td>URL         <td>https://spi.canonical.com/products
 <tr>
     <td>Method      <td>POST
 <tr>
     <td>Data        <td>
 <pre>
 {
-    “image_name”: "test\_image",
-    “release”: “15.04”,
-    “base_image_reference”: "http://foo.bar",
-    “snaps”: [['snap A', 1, true],['snap B', null, false]]
+  "primary_snap_name": "test-snap.foo",
+  "name": "test-product.foo",
+  "release": "15.04-core",
+  "snaps": [
+    "pi2.canonical",
+    "webdm.canonical",
+    "test-snap.foo"
+  ]
 }
 </pre>
 <tr>
@@ -217,33 +193,31 @@
 <tr>
     <td>Example     <td>
 <pre>
-$ ./scripts/api_example.py -X POST conf.ini  https://spi.canonical.com/orgs/docs-org/products/manifests --data '{
-  "image_name": "test_image",
-  "release": "15.04",
-  "base_image_reference": "http://foo.bar",
-  "snaps": [["snap A", 1, true],["snap B", null, false]]
+$ ./scripts/api_example.py -X POST conf.ini  https://spi.canonical.com/products --data '{
+  "primary_snap_name": "test-snap.foo",
+  "name": "test-product.foo",
+  "release": "15.04-core",
+  "snaps": [
+    "pi2.canonical",
+    "webdm.canonical",
+    "test-snap.foo"
+  ]
 }'
 
 HTTP 201
 {
-  "manifest": {
-    "image_name": "test_image",
+  "product": {
+    "created_at": "2016-01-04T16:58:25.835796",
+    "active": true,
     "snaps": [
-      {
-        "locked": true,
-        "revision": 1,
-        "name": "snap A"
-      },
-      {
-        "locked": false,
-        "revision": null,
-        "name": "snap B"
-      }
+      "pi2.canonical",
+      "webdm.canonical",
+      "test-snap.foo"
     ],
-    "base_image_reference": "http://foo.bar",
-    "id": "ae02b198-bfc8-4d26-aa7b-53dbfdd38230",
-    "release": "15.04",
-    "created_at": "2015-08-28T20:15:15.726057"
+    "release": "15.04-core",
+    "primary_snap_name": "test-snap.foo",
+    "name": "test-product.foo",
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
   }
 }
 </pre>
@@ -251,42 +225,39 @@
 
 <table class="table">
 <tr>
-    <th>Action  <th>Manifest Listing
+    <th>Action  <th>Product Listing
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/products/manifests
+    <td>URL     <td>https://spi.canonical.com/products
 <tr>
     <td>Method  <td>GET
 <tr>
     <td>Data    <td>N/A
 <tr>
-    <td>Response    <td><code>200</code> a JSON list of manifests
+    <td>Response    <td><code>200</code> a JSON list of products and packages for the user.
 <tr>
     <td>Example     <td>
 <pre>
-$ ./scripts/api_example.py conf.ini https://spi.canonical.com/orgs/docs-org/products/manifests
+$ ./scripts/api_example.py conf.ini https://spi.canonical.com/products
 
-HTTP 200
+HTTP  200
 {
-  "manifests": [
+  "products": [
     {
-      "image_name": "e2e-img8c80b8b271814262add99ccf4d3deba6",
-      "base_image_reference": "http://foo.com/bar",
+      "primary_snap_name": "test-snap.foo",
+      "active": true,
       "snaps": [
-        {
-          "revision": 1,
-          "name": "snap-a",
-          "locked": true
-        },
-        {
-          "revision": null,
-          "name": "snap-b",
-          "locked": false
-        }
+        "pi2.canonical",
+        "webdm.canonical",
+        "test-snap.foo"
       ],
-      "id": "9b2ff50c-5fab-4039-a5e5-1a9672d71223",
-      "release": "15.04",
-      "created_at": "2015-08-28T20:00:11.058236"
+      "release": "15.04-core",
+      "name": "test-product.e2e",
+      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
+      "created_at": "2016-01-04T17:34:39.093142"
     }
+  ],
+  "packages": [
+    "test-snap.foo"
   ]
 }
 </pre>
@@ -294,9 +265,9 @@
 
 <table class="table">
 <tr>
-    <th>Action  <th>Manifest View
+    <th>Action  <th>Product View
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/products/manifests/&lt;manifest-id&gt;
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;
 <tr>
     <td>Method  <td>GET
 <tr>
@@ -306,28 +277,22 @@
 <tr>
     <td>Example    <td>
 <pre>
-$ ./scripts/api_example.py conf.ini https://spi.canonical.com/orgs/docs-org/products/manifests/9b2ff50c-5fab-4039-a5e5-1a9672d71223
+$ ./scripts/api_example.py conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
-HTTP 200
+HTTP  200
 {
-  "manifest": {
-    "release": "15.04",
-    "base_image_reference": "http://foo.com/bar",
-    "id": "9b2ff50c-5fab-4039-a5e5-1a9672d71223",
-    "image_name": "e2e-img8c80b8b271814262add99ccf4d3deba6",
+  "product": {
+    "release": "15.04-core",
     "snaps": [
-      {
-        "locked": true,
-        "name": "snap-a",
-        "revision": 1
-      },
-      {
-        "locked": false,
-        "name": "snap-b",
-        "revision": null
-      }
+      "pi2.canonical",
+      "webdm.canonical",
+      "test-snap.foo"
     ],
-    "created_at": "2015-08-28T20:00:11.058236"
+    "primary_snap_name": "test-snap.foo",
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "created_at": "2016-01-04T17:34:39.093142",
+    "name": "test-product.foo",
+    "active": true
   }
 }
 </pre>
@@ -336,16 +301,16 @@
 
 <table class="table">
 <tr>
-    <th>Action  <th>Manifest Deactivation/Reactivation
+    <th>Action  <th>Product Deactivation/Reactivation
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/products/manifests/&lt;manifest-id&gt;
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;
 <tr>
     <td>Method  <td>PUT
 <tr>
     <td>Data    <td>
 <pre>
 {
-  “active”: "false",  # or “true” to reactivate
+  "active": "false",  # or "true" to reactivate
 }
 </pre>
 <tr>
@@ -354,7 +319,9 @@
     <td>Example    <td>
 <pre>
 $ ./scripts/api_example.py -X PUT conf.ini \
-https://spi.canonical.com/orgs/docs-org/products/manifests/9b2ff50c-5fab-4039-a5e5-1a9672d71223
+https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -data '{
+    "active": "true"
+}'
 
 HTTP 200
 {
@@ -364,9 +331,9 @@
 
 <table class="table">
 <tr>
-    <th>Action  <th>Manifest Deletion
+    <th>Action  <th>Product Deletion
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/products/manifests/&lt;manifest-id&gt;
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;
 <tr>
     <td>Method  <td>DELETE
 <tr>
@@ -377,36 +344,154 @@
     <td>Example    <td>
 <pre>
 $ ./scripts/api_example.py -X DELETE conf.ini \
-https://spi.canonical.com/orgs/docs-org/products/manifests/9b2ff50c-5fab-4039-a5e5-1a9672d71223
-
-HTTP 200
-{
-  "ok": true
-}
-</table>
+https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+HTTP 200
+{
+  "ok": true
+}
+</table>
+
+Base Image Management
+---------------------
+
+Base Images are automatically created. The user can mark them as released, to indicate that
+the specific combination of snaps is representative of a product release, or as active/inactive
+to mark them as not useful anymore.
+
+<table class="table">
+<tr>
+    <th>Action  <th>Base Image Listing
+<tr>
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/baseimages
+<tr>
+    <td>Method  <td>GET
+<tr>
+    <td>Data    <td>N/A
+<tr>
+    <td>Response    <td><code>200 OK</code> and a JSON representation of the available baseimages
+<tr>
+    <td>Example    <td>
+<pre>
+$ ./scripts/api_example.py conf.ini \
+https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/baseimages
+
+HTTP  200
+{
+  "baseimages": [
+    {
+      "released_at": null,
+      "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "snaps": [
+        {
+          "name": "test-snap.foo",
+          "revision": 1
+        },
+        {
+          "name": "webdm.canonical",
+          "revision": 1
+        },
+        {
+          "name": "pi2.canonical",
+          "revision": 1
+        }
+      ],
+      "channel": "stable",
+      "created_at": "2016-01-04T18:45:48.853476",
+      "active": true,
+      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    }
+  ]
+}
+</table>
+
+<table class="table">
+<tr>
+    <th>Action  <th>Base Image Viewing
+<tr>
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/baseimages/&lt;image-id&gt;
+<tr>
+    <td>Method  <td>GET
+<tr>
+    <td>Data    <td>N/A
+<tr>
+    <td>Response    <td><code>200 OK</code> and a JSON representation of the base image.
+<tr>
+    <td>Example    <td>
+<pre>
+$ ./scripts/api_example.py conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/baseimages/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+HTTP  200
+{
+  "baseimage": {
+    "created_at": "2016-01-04T18:45:48.853476",
+    "channel": "stable",
+    "active": true,
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "snaps": [
+      {
+        "name": "test-snap.foo",
+        "revision": 1
+      },
+      {
+        "name": "webdm.canonical",
+        "revision": 1
+      },
+      {
+        "name": "pi2.canonical",
+        "revision": 1
+      }
+    ],
+    "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "released_at": null
+  }
+}
+</table>
+
+<table class="table">
+<tr>
+    <th>Action  <th>Base Image Updating
+<tr>
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/baseimages/&lt;image-id&gt;
+<tr>
+    <td>Method  <td>PUT
+<tr>
+    <td>Data    <td>
+<pre>
+{
+  "active": "false",  # or "true" to reactivate
+  "released": "true",  # or "false"
+}
+</pre>
+<tr>
+    <td>Response    <td><code>200 OK</code>
+<tr>
+    <td>Example    <td>
+<pre>
+$ ./scripts/api_example.py -X PUT conf.ini \
+https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/baseimages/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -data '{
+    "released": "true"
+}'
+
+HTTP 200
+{
+  "ok": true
+}
+</table>
+
+
 
 Test Management
 ---------------
 
 Tests are defined with Test Specs. There may be multiple
-Test Specs per product and they are related via the image\_name field.
-TestSpecs are required for both Image and Snappy based workflows as they
-form the basis for TestOpportunity creation.
-
-Test Specs are immutable but may be deleted or deactivated to be
-hidden from view. The details of the Test Spec that led to a Test
-Opportunity is always persisted in the Test Result data.
-
-To modify a Test Spec, the user should delete the existing one and
-create a new one with the desired changes. That will not automatically
-trigger new tests, for that see [Test
-Triggering](#test-triggering).
+Test Specs per product and they form the basis for TestOpportunity creation.
 
 <table class="table">
 <tr>
     <th>Action  <th>Test Spec Creation
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/tests/specs
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/tests/specs
 <tr>
     <td>Method  <td>POST
 <tr>
@@ -414,10 +499,10 @@
 <pre>
 {
   "platform": platform of the product
-  "name": unique (within an org) name of the Test
-  "image_name": name that ties this test to the product/manifest
+  "name": unique (within the product) name of the Test
   "test_payload": an arbitrary JSON value with all the information needed to run the test
                   (maximum size 4000 bytes), optional defaulting to null
+  "channel_combos": **FIXME DESCRIBE**
 }
 </pre>
 <tr>
@@ -428,21 +513,43 @@
 $ ./scripts/api_example.py -X POST conf.ini https://spi.canonical.com/orgs/docs-org/tests/specs \
 --data '
 {
+  "name": "foo-spec_bar",
   "platform": "amd64",
-  "image_name": "imgname",
-  "name": "specname32"
+  "channel_combos": [
+    {
+      "update": "edge",
+      "base": "stable"
+    }
+  ],
+  "test_payload": "{'foo': 'bar'}"
 }'
 
 HTTP 201
+Location: https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tests/specs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 {
   "spec": {
-    "image_name": "imgname",
-    "id": "cd98a77f-f7da-4388-b007-0a8a3604b676",
-    "name": "specname32",
+    "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "created_at": "2016-01-04T16:58:26.357538",
+    "active": true,
     "platform": "amd64",
-    "created_at": "2015-08-28T20:28:46.334756",
-    "test_payload": null
-  }
+    "test_payload": "{'foo': 'bar'}",
+    "name": "foo-spec_bar",
+    "channel_combos": [
+      {
+        "update": "edge",
+        "base": "stable"
+      }
+    ],
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  },
+  "test_ids": [
+    [
+      {
+        "image_unique_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        "test_opportunity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    ]
+  ]
 }
 </pre>
 </table>
@@ -451,7 +558,7 @@
 <tr>
     <th>Action  <th>Test Spec List
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/tests/specs
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/tests/specs
 <tr>
     <td>Method  <td>GET
 <tr>
@@ -461,18 +568,25 @@
 <tr>
     <td>Example    <td>
 <pre>
-$ ./scripts/api_example.py conf.ini https://spi.canonical.com/orgs/docs-org/tests/specs
+$ ./scripts/api_example.py conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tests/specs
 
-HTTP 200
+HTTP  200
 {
   "specs": [
     {
-      "created_at": "2015-08-28T20:28:46.334756",
-      "id": "cd98a77f-f7da-4388-b007-0a8a3604b676",
-      "test_payload": null,
-      "image_name": "imgname",
+      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "active": true,
+      "created_at": "2016-01-04T17:34:39.626802",
+      "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "test_payload": "{'foo': 'bar'}",
+      "name": "foo-spec_bar",
       "platform": "amd64",
-      "name": "specname32"
+      "channel_combos": [
+        {
+          "update": "edge",
+          "base": "stable"
+        }
+      ]
     }
   ]
 }
@@ -483,7 +597,7 @@
 <tr>
     <th>Action  <th>Test Spec View
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/<org-id>/tests/specs/<spec-id>
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/tests/specs/&lt;spec-id&gt;
 <tr>
     <td>Method  <td>GET
 <tr>
@@ -493,17 +607,24 @@
 <tr>
     <td>Example    <td>
 <pre>
-$ ./scripts/api_example.py conf.ini https://spi.canonical.com/orgs/docs-org/tests/specs/cd98a77f-f7da-4388-b007-0a8a3604b676
+$ ./scripts/api_example.py conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tests/specs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
 HTTP 200
 {
   "spec": {
-    "id": "cd98a77f-f7da-4388-b007-0a8a3604b676",
-    "name": "specname32",
-    "platform": "amd64",
-    "created_at": "2015-08-28T20:28:46.334756",
-    "test_payload": null,
-    "image_name": "imgname"
+      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "active": true,
+      "created_at": "2016-01-04T17:34:39.626802",
+      "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "test_payload": "{'foo': 'bar'}",
+      "name": "foo-spec_bar",
+      "platform": "amd64",
+      "channel_combos": [
+        {
+          "update": "edge",
+          "base": "stable"
+        }
+      ]
   }
 }
 
@@ -514,14 +635,14 @@
 <tr>
     <th>Action  <th>Test Spec Deactivation/Reactivation
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/<org-id>/tests/specs/<spec-id>
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/tests/specs/&lt;spec-id&gt;
 <tr>
     <td>Method  <td>PUT
 <tr>
     <td>Data    <td>
 <pre>
 {
-  “active”: "false",  # or “true” to reactivate
+  "active": "false",  # or "true" to reactivate
 }
 </pre>
 <tr>
@@ -530,7 +651,10 @@
     <td>Example    <td>
 <pre>
 $ ./scripts/api_example.py -X PUT conf.ini \
-https://spi.canonical.com/orgs/docs-org/tests/specs/cd98a77f-f7da-4388-b007-0a8a3604b676
+https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tests/specs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --data '
+{
+  "active": "false"
+}'
 
 HTTP 200
 {
@@ -543,7 +667,7 @@
 <tr>
     <th>Action  <th>Test Spec Deletion
 <tr>
-    <td>URL     <td>https://spi.canonical.com/orgs/<org-id>/tests/specs/<spec-id>
+    <td>URL     <td>https://spi.canonical.com/products/&lt;product-id&gt;/tests/specs/&lt;spec-id&gt;
 <tr>
     <td>Method  <td>DELETE
 <tr>
@@ -554,7 +678,7 @@
     <td>Example    <td>
 <pre>
 $ ./scripts/api_example.py -X DELETE conf.ini \
-https://spi.canonical.com/orgs/docs-org/tests/specs/cd98a77f-f7da-4388-b007-0a8a3604b676
+https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tests/specs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
 HTTP 200
 {
@@ -562,6 +686,7 @@
 }</pre>
 </table>
 
+
 Test Triggering
 ---------------
 
@@ -572,7 +697,6 @@
 has the following required fields:
 
 
-
 -   ```image_name```: a unique name within an
     organization that is combined with each
     test case to produce the full set of test