api-ref: update interoperable image import info

Generalizes the discussion to include the new web-download import
method and includes a new sample import request.

Change-Id: Icb6cd920f31c6e8e4eecf17880dd3244e5d1a61b
Closes-bug: #1748229

api-ref/source/heading-level-guide.txt

@@ -0,0 +1,31 @@
+===============
+Heading level 1
+===============
+
+ReStructured Text doesn't care what markers you use for headings,
+but it does require you to be consistent.  Here's what we are using
+in the Image API reference documents.
+
+Level 1 is mostly used in the .rst files.  For the .inc files,
+the top-level heading will most likely be a Level 2.
+
+Heading level 2
+***************
+
+Heading level 3
+~~~~~~~~~~~~~~~
+
+Heading level 4
+---------------
+
+Heading level 5
++++++++++++++++
+
+Heading level 6
+###############
+
+Heading level 7
+"""""""""""""""
+
+Heading level 8
+'''''''''''''''

api-ref/source/v2/images-import.inc

@@ -7,7 +7,7 @@ Interoperable image import
 
 An interoperable image import process is introduced in the Image API v2.6.
 
-Use the :ref:`API versions call <versions-call>` to determine what API verisons
+Use the :ref:`API versions call <versions-call>` to determine what API versions
 are available in your cloud.
 
 General information
@@ -26,8 +26,12 @@ Two import methods are defined, ``glance-direct`` and ``web-download``.
    to determine what import methods are available in the cloud to which
    you wish to import an image.
 
+The first step in each interoperable image import method is the same: you must
+create an image record.  This will give you an image id to work with.  This
+image id is how the OpenStack Image service will understand that the other
+calls you make are referring to this particular image.
 
-The ``glance-direct`` workflow has three parts:
+Thus, the first step is:
 
 1.  Create an image record using the :ref:`Image Create <image-create>`
     API call.  You must do this first so that you have an image id to
@@ -40,14 +44,31 @@ The ``glance-direct`` workflow has three parts:
     methods may be determined independently of creating an image by making
     the :ref:`Import Method Discovery <import-discovery-call>` call.
 
+The glance-direct import method
+-------------------------------
+
+The ``glance-direct`` workflow has **three** parts:
+
+1.  Create an image record as described above.
+
 2.  Upload the image data to a staging area using the :ref:`Image Stage
     <image-stage-call>` API call.  Note that this image data is not
     accessible until after the third step has successfully completed.
 
 3.  Issue the :ref:`Image Import <image-import-call>` call to complete
-    the import process.
+    the import process.  You will specify that you are using the
+    ``glance-direct`` import method in the body of the import call.
 
-.. TODO(rosmaita): describe the web-download workflow
+The web-download import method
+------------------------------
+
+The ``web-download`` workflow has **two** parts:
+
+1.  Create an image record as described above.
+
+2.  Issue the :ref:`Image Import <image-import-call>` call to complete
+    the import process.  You will specify that you are using the
+    ``web-download`` import method in the body of the import call.
 
 .. _image-stage-call:
 
@@ -126,32 +147,63 @@ Import an image
 .. rest_method::  POST /v2/images/{image_id}/import
 
 Signals the Image Service to complete the image import workflow
-by processing the previously staged image data.
+by processing data that has been made available to the OpenStack
+image service.
 *(Since Image API v2.6)*
 
+In the ``glance-direct`` workflow, the data has been made available to the
+Image service via the :ref:`Stage binary image data <image-stage-call>` API
+call.
+
+In the ``web-download`` workflow, the data is made available to the Image
+service by being posted to an accessible location with a URL that you know.
+
 Example call: ``curl -i -X POST -H "X-Auth-Token: $token"
 $image_url/v2/images/{image_id}/import``
 
 The JSON request body specifies what import method you wish to use
 for this image request.
 
-.. TODO(rosmaita): rewrite to include web-download info
+**Preconditions**
 
-Before you can complete the ``glance-direct`` image import workflow, you
+Before you can complete the interoperable image import workflow, you must meet
-must meet the following preconditions:
+the following preconditions:
 
 - The image record must exist.
 
-- You must set the disk and container formats in the image.
+- You must set the disk and container formats in the image record.  (This can
-
+  be done at the time of image creation, or you can make the :ref:`Image Update
-- The image status must be ``uploading``.  (This indicates that the image
+  <v2-image-update>` API call.
-  data has been uploaded to the stage.)
 
 - Your image storage quota must be sufficient.
 
 - The size of the data that you want to store must not exceed the
   size that the OpenStack Image service allows.
 
+**Additional Preconditions**
+
+If you are using the ``glance-direct`` import method:
+
+- The image status must be ``uploading``.  (This indicates that the image
+  data has been uploaded to the stage.)
+
+- The body of your request must indicate that you are using the
+  ``glance-direct`` import method.
+
+If you are using the ``web-download`` import method:
+
+- The image status must be ``queued``.  (This indicates that no image data
+  has yet been associated with the image.)
+
+- The body of your request must indicate that you are using the
+  ``web-download`` import method, and it must contain the URL at which the data
+  is to be found.
+
+  .. note::
+     The acceptable set of URLs for the ``web-download`` import method may be
+     restricted in a particular cloud.  Consult the cloud's local documentation
+     for details.
+
 **Synchronous Postconditions**
 
 - With correct permissions, you can see the image status as
@@ -172,14 +224,20 @@ Request
 
 .. rest_parameters:: images-parameters.yaml
 
-   - Content-type: Content-Type-data
+   - Content-type: Content-Type-json
    - image_id: image_id-in-path
    - method: method-in-request
 
-Request Example
+Request Example - glance-direct import method
-----------------
+---------------------------------------------
 
-.. literalinclude:: samples/image-import-request.json
+.. literalinclude:: samples/image-import-g-d-request.json
+   :language: json
+
+Request Example - web-download import method
+--------------------------------------------
+
+.. literalinclude:: samples/image-import-w-d-request.json
    :language: json
 
 

api-ref/source/v2/samples/image-import-w-d-request.json

@@ -0,0 +1,6 @@
+{
+    "method": {
+        "name": "web-download",
+        "uri": "https://download.cirros-cloud.net/0.4.0/cirros-0.4.0-ppc64le-disk.img"
+    }
+}

api-ref/source/v2/samples/image-info-import-response.json

@@ -3,7 +3,8 @@
         "description": "Import methods available.",
         "type": "array",
         "value": [
-            "glance-direct"
+            "glance-direct",
+            "web-download"
         ]
     }
 }