========================
Manage images using cURL
========================

This section is intended to provide a series of commands a typical
client of the API might use to create and modify an image.

These commands assume the implementation of the v2 Image API using
the Identity Service for authentication and authorization. The
X-Auth-Token header is used to provide the authentication token issued by
the Identity Service.

The strings ``$OS_IMAGE_URL`` and ``$OS_AUTH_TOKEN`` represent variables
defined in the client's environment. ``$OS_IMAGE_URL`` is the full path
to your image service endpoint, for example, ``http://example.com``.
``$OS_AUTH_TOKEN`` represents an auth token generated by the
Identity Service, for example, ``6583fb17c27b48b4b4a6033fe9cc0fe0``.

Create an image
~~~~~~~~~~~~~~~

.. code-block:: console

    $ curl -i -X POST -H "X-Auth-Token: $OS_AUTH_TOKEN" \
           -H "Content-Type: application/json" \
           -d '{"name": "Ubuntu 14.04", \
           "tags": ["ubuntu", "14.04", "trusty"]}' \
           $OS_IMAGE_URL/v2/images

    HTTP/1.1 201 Created
    Content-Length: 451
    Content-Type: application/json; charset=UTF-8
    Location: http://example.com:9292/v2/images
              /7b97f37c-899d-44e8-aaa0-543edbc4eaad
    Date: Fri, 11 Mar 2016 12:25:32 GMT

    {
        "id": "7b97f37c-899d-44e8-aaa0-543edbc4eaad",
        "name": "Ubuntu 14.04",
        "status": "queued",
        "visibility": "private",
        "protected": false,
        "tags": ["ubuntu", "14.04", "trusty"],
        "created_at": "2016-03-11T12:25:32Z",
        "updated_at": "2016-03-11T12:25:32Z",
        "file": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file",
        "self": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad",
        "schema": "/v2/schemas/image"
    }

Update the image
~~~~~~~~~~~~~~~~

.. code-block:: console

    $ curl -i -X PATCH -H "X-Auth-Token: $OS_AUTH_TOKEN" \
           -H "Content-Type: application/json" \
           -d '[{"op": "add", "path": "/login-user", "value": "root"}]' \
           $OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad

    HTTP/1.1 200 OK
    Content-Length: 477
    Content-Type: application/json; charset=UTF-8
    Date: Fri, 11 Mar 2016 12:44:56 GMT

    {
        "id": "7b97f37c-899d-44e8-aaa0-543edbc4eaad",
        "name": "Ubuntu 14.04",
        "status": "queued",
        "visibility": "private",
        "protected": false,
        "tags": ["ubuntu", "14.04", "trusty"],
        "login_user": "root",
        "created_at": "2016-03-11T12:25:32Z",
        "updated_at": "2016-03-11T12:44:56Z",
        "file": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file",
        "self": "/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad",
        "schema": "/v2/schemas/image"
    }

Upload binary image data
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

    $ curl -i -X PUT -H "X-Auth-Token: $OS_AUTH_TOKEN" \
           -H "Content-Type: application/octet-stream" \
           --data-binary @/home/glance/ubuntu-14.04.qcow2 \
           $OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file

    HTTP/1.1 100 Continue
    HTTP/1.1 201 Created
    Content-Length: 0
    Date: Fri, 11 Mar 2016 12:51:02 GMT

Download binary image data
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

    $ curl -i -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" \
           $OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad/file

    HTTP/1.1 200 OK
    Content-Type: application/octet-stream
    Content-Md5: 912ec803b2ce49e4a541068d495ab570
    Transfer-Encoding: chunked
    Date: Fri, 11 Mar 2016 12:57:41 GMT

Delete an image
~~~~~~~~~~~~~~~

.. code-block:: console

    $ curl -i -X DELETE -H "X-Auth-Token: $OS_AUTH_TOKEN" \
           $OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad

    HTTP/1.1 204 No Content
    Content-Length: 0
    Date: Fri, 11 Mar 2016 12:59:11 GMT