Merge lp:~noise/tanuki-agent/just-the-facts into lp:tanuki-agent

[Bret Barker]

remove extras from api ref; clean SPI refs

[Guillermo Gonzalez (verterok)]

lots of red, that's usually good. +1

review: Approve

=== modified file 'docs/api-reference.md'
--- docs/api-reference.md	2015-11-04 14:37:58 +0000
+++ docs/api-reference.md	2015-11-04 21:52:03 +0000
@@ -1,59 +1,14 @@
-Title:   Snappy Product Integration API Guide
-Version: 20151030
+Title:   Ubuntu Core Product Integration API Guide
+Version: 20151105
 
 [TOC]
 
-System Overview
-===============
-
-Snappy Product Integration(SPI) is system for
-coordinating integration testing of Snappy-based products
-across a matrix of supported platforms.
-
-
-
-It is important to note that SPI is not a build tool, image
-composer, or unit test runner.
-
-
-
-There are four main actors in SPI:
-
--   Product Owners managing product definitions
--   Developers providing Snaps or Images for test
-
-<!-- -->
-
--   Lab owners managing hardware installations that will consume
-    tests
--   Quality Assurance engineers that will manage tests and
-    evaluate test results
-
-
-
-This separation of concerns is enforced by the design of the SPI
-System and the APIs it provides. Below is a diagram of the
-overall architecture and data flow. The blue boxes form the SPI software
-provided by Canonical. The green boxes represent your organization’s
-different responsibilities. They also represent the middle layer you
-provide for the SPI system to talk to your hardware known as the
-Provisioning Kit.
-
-![](images/image02.png)
-
-SPI Definitions
----------------
-
-
-
-SPI models product integration testing using the following core
-abstractions:
-
-
+
+Definitions
+============
 
 -   **Manifest**: used to define a Product
-    that is based on Snaps. This is optional for image-based workflows
-    as detailed below under [Workflows](#workflows).
+    that is based on Snaps. This is optional for image-based workflows.
 -   **Image Reference**: information passed
     to the Provisioning Kit to use in setting up a device for testing
     the Product. It is free-form with data of your choosing (e.g. a
@@ -62,61 +17,13 @@
 -   **Test Spec**: defines Tests to be run on
     matching images
 -   **Test Opportunity**: an instance of a
-    test for a given image that will be delivered to an Agent.
--   **Agent**: SPI client installed in a
-    "lab" to coordinate running tests.
--   **Test Result**: metadata
-    about output of a test run.
-
-
-
-
-
-Workflows
----------
-
-
-
-There are two primary workflows supported by SPI:
-
-
-
-1.  Snappy Based Image
-2.  Custom Image
-
-
-
-In the Snappy scenario, the product owner will first create a
-Product (Manifest) and Test Specs in SPI. The product will point to a
-base image that defines the "released" product and specify the names of
-Snaps that comprise the product. Changes to the named Snaps, represented
-as new uploads to the Snappy Store,  will be automatically advertised to
-the SPI system to trigger tests of the base image with updated Snaps.
-
-
-
-
-As an example, Canonical’s Snappy Core team uses this workflow to
-perform integration, upgrade, and downgrade testing as each new revision
-of the WebDM Snap is uploaded to the Store.
-
-
-
-The Custom Image workflow is simpler and designed to
-help you transition from legacy product image testing to a
-Snappy-generated product while running the same tests in the same manner
-throughout this period. In this scenario, the product owner
-(or developer) can create Test Specs (no Manifest required) and then
-submit Images that match the Test Spec based on image\_name to trigger
-test runs.
-
-API Reference
-=============
+    test for a given image and/or set of snaps that will be delivered to an Agent.
+-   **Agent**: Client software installed on a host computer to run
+    tests against a target device.
+-   **Test Result**: metadata about output of a test run.
 
 Authentication
---------------
-
-
+============
 
 All API endpoints are authenticated, which ensures private access
 to your Organization's information.
@@ -129,7 +36,7 @@
 <!-- LINK TO CORRECT PLACE IN TUTORIAL? -->
 
 With those credentials, you can use an oauth library in your
-language of choice to sign HTTP requests to the SPI API endpoints.
+language of choice to sign HTTP requests to the API endpoints.
 
 
 We'll walk through an example of that in Python using <span
@@ -203,10 +110,10 @@
 login process) into a file called conf.ini. Note, this script is meant only as an example and not
 intended for production use.
 
-API Errors
-----------
+Errors
+============
 
-The SPI APIs use standard HTTP response codes. Most errors will
+The APIs use standard HTTP response codes. Most errors will
 contain a human-readable "message" field in the JSON response body. Here
 are the most common error codes and guidelines for handling them.
 
@@ -230,14 +137,17 @@
         <p>There was an temporary error on the server. The request may be retried after a short wait. If the problem persists please contact support. Scripts should use an exponential backoff to avoid hammering the servers with retries.
 </table>
 
+API Reference
+=============
+
 Product Management
 ------------------
 
 Note: Product Manifests support products built from
-Snaps. If you are instead bootstrapping SPI with a pre-existing binary
+Snaps. If you are instead bootstrapping Product Integration with a pre-existing binary
 image, please skip ahead to the next section - Test Management.
 
-In SPI, a Product is defined by a Manifest that has an image\_name
+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.
 
@@ -266,7 +176,7 @@
 -   ```release``` snappy release series, e.g.
     “15.04”. Maximum length is 200 characters.
 -   ```base_image_reference``` is opaque to
-    the SPI system; it is for your Provisioning Kit in your lab 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
@@ -478,7 +388,7 @@
 Test Management
 ---------------
 
-Tests in SPI are defined with Test Specs. There may be multiple
+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.
@@ -658,7 +568,7 @@
 ### Image Submission
 
 Test opportunities are triggered by a new image reference being
-advertised by the user to the SPI system. An Image Reference
+advertised by the user to the system. An Image Reference
 has the following required fields:
 
 
@@ -670,13 +580,13 @@
     matching image_name, then two test opportunities will be created.
     Maximum length is 200 characters.
 -   ```image_reference```: is opaque to the
-    SPI system; it is for your Provisioning Kit in your lab
+    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.
 -   ```image_unique_id```: also opaque to the
-    SPI system. It is recommended that this uniquely
+    system. It is recommended that this uniquely
     identifies the advertised version of the image so that the
     provisioning script can verify the image\_reference and results can
     be queried by image\_unique\_id. For example it could
@@ -737,10 +647,10 @@
 ### Snap Revisions
 
 Test opportunities may be triggered by snap revisions being
-advertised to the SPI system.
+advertised to the system.
 
 New snap revisions uploaded to the Store will be automatically
-advertised to SPI, however they can be re-advertised manually
+advertised to the system, however they can be re-advertised manually
 afterwards, re-triggering tests with their original context.
 
 The new revision advertised will be matched with all **Manifests** within the context **Organization**
@@ -782,7 +692,7 @@
 
 
 
-SPI will return a list of test opportunity IDs and image unique IDs that can be used to [query for results](#querying-test-results) later.
+Snap revision advertisement will return a list of test opportunity IDs and image unique IDs that can be used to [query for results](#querying-test-results) later.
 
 <table class="table">
 <tr>
@@ -877,7 +787,7 @@
 <p>Using with_event=EVENT_TYPE will return only logs that contain that event type.
 For example with_event=RESULT_POSTED returns only logs for tests for which a result has been posted back. Using without_event=EVENT_TYPE will return only logs that do not contain that event type. with_event and without_event cannot be used in the same query.
 
-<p>For example, a large number of results that match without_event=PICKED_BY_AGENT could indicate either an under-resourced lab (all agents are busy) or that the agents have lost communication with the SPI servers. The combination of with_event=PICKED_BY_AGENT and without_event=RESULT_POSTED can be used to track down slow or stuck test runs, and the agent_id fields of the PICKED_BY_AGENT event can be used to identify the problem agent in the lab.
+<p>For example, a large number of results that match without_event=PICKED_BY_AGENT could indicate either an under-resourced lab (all agents are busy) or that the agents have lost communication with Canonical's servers. The combination of with_event=PICKED_BY_AGENT and without_event=RESULT_POSTED can be used to track down slow or stuck test runs, and the agent_id fields of the PICKED_BY_AGENT event can be used to identify the problem agent in the lab.
 <tr>
     <td>Response    <td><code>200 OK</code> with JSON list of matching progress event log documents
 <tr>
 
=== removed file 'docs/images/image02.png'
 Binary files docs/images/image02.png	2015-11-02 16:58:53 +0000 and docs/images/image02.png	1970-01-01 00:00:00 +0000 differ