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.

../../../_images/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:

../../../_images/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:

{
  "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

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

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 interface can be used to query existing series within an index.

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

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

<?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

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 this section.

Add an entry

URL <catalog-base-url>/<index-name>
HTTP Verb POST
Authentication Terradue username and password (or API key)
Request content

Content-type: application/atom+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 Create entries.

For information on the data model and examples of typical entry content, see Metadata models.

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

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.