.. _catalog-rest-api:

Ellip Catalog REST API
========================

The ``<catalog-base-url>`` placeholder has to be replaced with the base URL of a catalog instance. Terradue's main catalog the value would be **https://catalog.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.



Catalog routes
----------------

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

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

The operation part can also be absent and the HTTP verb defines it. (e.g. POST for creation, PUT for update)

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

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

This request would produce a search result from the series *italy* of index *mrossi*.


Requests
--------

As usual with REST-ful interfaces, the requests can either be empty or have a content (or payload), depending on the operation.

With the catalog, when there has to be a request content, it is usually an ATOM document. 


Responses
---------

Successful operations return JSON documents like the following where the "*...*" are replaced with the appropriate values:

.. code-block:: json

    {
      "added": ...,
      "updated": ...,
      "deleted": ...,
      "errors": ...,
      "items": [
          {
              "id": "...",
              "type": "...",
              "operation": "..."
          }
      ]
    }


    
Operations on indices
---------------------

Indices are at the level directly below the catalog's root and provide the container for catalog data of all kinds. There are public indices for shared data and personal and private indices of users.


List indices
^^^^^^^^^^^^
..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<catalog-base-url>``
    * - HTTP Verb
      - GET
    * - Authentication
      - HTTP basic authentication using Ellip username and password (or API key)
    * - Response
      - JSON document containing the indices
    * - Request content
      - N/A
    * - Response
      - JSON document containing the indices



Add an index
^^^^^^^^^^^^

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

    * - URL
      - ``<catalog-base-url>``/``<index-name>``
    * - HTTP Verb
      - PUT
    * - Authentication
      - HTTP basic authentication using Ellip username and password (or API key)
    * - Request content
      - None
    * - Response
      - JSON document containing the indices

      

Operations on series
--------------------

Series provide a way of organising entries in an index based on shared criteria and can be thought of as something similar to views in a relational database.


List series
^^^^^^^^^^^

The catalog's `OpenSearch <opensearch>`_ interface can be used to query existing series within an index.

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

    * - URL
      - ``<catalog-base-url>``/``<index-name>``/series/search
    * - HTTP Verb
      - GET
    * - Authentication
      - HTTP basic authentication using Ellip username and password (or API key)
    * - Response
      - ATOM document (other formats available, according to the description available at ``<catalog-base-url>``/``<index-name>``/series/description) 


Add a series
^^^^^^^^^^^^
..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<catalog-base-url>``/``<index-name>``/series
    * - HTTP Verb
      - POST
    * - Authentication
      - Terradue username and password (or API key)
    * - Request content
      - Content-type: application/atom+xml

        ..  code-block:: xml
        
            <?xml version="1.0" encoding="utf-8"?>
            <feed xmlns="http://www.w3.org/2005/Atom">
              <entry>
                <title type="text">TITLE</title>
                <link rel="describedBy" type="application/atom+xml" title="LINK-TITLE" href="URL"/>
                <identifier xmlns="http://purl.org/dc/elements/1.1/">IDENTIFIER</identifier>
              </entry>
            </feed>
            
        Capitalised parts must be replaced with actual content or values; ``URL`` should be an OpenSearch URL that selects a subset of entries.
            
    * - Response
      - JSON document containing the result of the operation, there should be a positive value for ``added`` and/or ``updated``.

      
      
Update a series
^^^^^^^^^^^^^^^

This works in exactly the same way as adding the series. A series is replaced if it already exists (based on the content of the `identifier` element). 


Delete a series
^^^^^^^^^^^^^^^

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

    * - URL
      - ``<catalog-base-url>``/``<index-name>``/series/``<series-identifier>``
    * - HTTP Verb
      - DELETE
    * - Authentication
      - HTTP basic authentication using Ellip username and password (or API key)
    * - Response
      - JSON document containing the result of the operation, there should be a positive value for ``deleted``.



Operations on entries
---------------------

Entries are the items at the lowest level in the catalog and usually correspond to EO products whose metadata they contain. But there are other types of entries, such as data items that can carry more and different information.


List entries
^^^^^^^^^^^^

This is equivalent to searching for entries and is covered in :ref:`this section <catalog-search-api>`.


Add an entry
^^^^^^^^^^^^
..  list-table::
    :widths: 10 90
    :header-rows: 0

    * - URL
      - ``<catalog-base-url>``/``<index-name>``
    * - HTTP Verb
      - POST
    * - Authentication
      - Terradue username and password (or API key)
    * - Request content
      - Content-type: application/atom+xml

        ..  code-block:: xml
        
            <feed xmlns="http://www.w3.org/2005/Atom">
              <entry>
                <id>entry1</id>
                <identifier xmlns="http://purl.org/dc/elements/1.1/">IDENTIFIER</identifier>
                <title type="text">TITLE</title>
                <summary type="html">HTML_SUMMARY</summary>
                <date xmlns="http://purl.org/dc/elements/1.1/">DATE_OR_PERIOD</date>
                <spatial xmlns="http://purl.org/dc/terms/">GEOMETRY_WKT</spatial>
                <published>PUBLISHED_DATE</published>
                <link rel="enclosure" type="application/octet-stream" length="4195720" href="DOWNLOAD_URL" />
                <!-- specific fields describing dataset -->
              </entry>
            </feed>

        Capitalised parts must be replaced with actual content or values.
            
    * - Response
      - JSON document containing the result of the operation, there should be a positive value for ``added`` and/or ``updated``.


For a guided example of an entry creation, see :ref:`datacreateentries`.

For information on the data model and examples of typical entry content, see :ref:`metadatamodel`.


Update an entry
^^^^^^^^^^^^^^^

This works in exactly the same way as adding the entry. An entry is replaced if it already exists (based on the content of the `identifier` element). 


Delete an entry
^^^^^^^^^^^^^^^

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

    * - URL
      - ``<catalog-base-url>``/``<index-name>``/search?uid=``<dataset-identifier>``
    * - HTTP Verb
      - DELETE
    * - Authentication
      - HTTP basic authentication using Ellip username and password (or API key)
    * - Response
      - JSON document containing the result of the operation, there should be a positive value for ``deleted``.