.. _storage-rest-api:

Ellip Storage REST API
======================

The ``<storage-base-url>`` placeholder has to be replaced with the base URL of a storage instance. Terradue's main catalog the value would be **https://store.terradue.com**

The catalog API uses a REST-ful interface that can be easily exploited with widely used tools.



Authentication
--------------

One of most important parameter to set in those REST commands is your API key which is configured in your profile page in the portal.

REST API supports two forms of authentication:

* Basic authentication using your username and password.
* Basic authentication using your username and API Key.



Storage routes
--------------

The storage has a hierarchiy of items and the **routes** following from that hierarchy are semantically important.

.. figure:: includes/storage-routes_1.png

An example for a URL corresponding to a valid route is the following:

.. figure:: includes/storage-routes_2.png


List directory content
----------------------

..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<storage-base-url>``/``<repository>``/[``directory``/]*
        
        .. note:: Directory URLs must end with a slash.   
      
    * - HTTP Verb
      - GET
    * - Authentication
      - Terradue username and password (or API key).
    * - Response
      - HTML document listing the directory content.



Download file
-------------

..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<storage-base-url>``/``<repository>``/[``directory``/]\* ``file``
    * - HTTP Verb
      - GET
    * - Authentication
      - Terradue username and password (or API key).
    * - Response
      - The file content.

      
      
Upload file
-----------

..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<storage-base-url>``/``<repository>``/[``directory``/]\* ``file``
    * - HTTP Verb
      - PUT
    * - Authentication
      - Terradue username and password (or API key).
    * - Request content
      - Content-type: application/octet-stream (or other, e.g. an image type).
    * - Response
      - JSON document containing the result of the operation, the creation time should be reported in ``created``.

      
      


Delete file or directory 
------------------------

..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<storage-base-url>``/``<repository>``/[``directory``/]\* ``file``
    * - HTTP Verb
      - DELETE
    * - Authentication.
      - HTTP basic authentication using Ellip username and password (or API key).
    * - Response
      - Empty.