REST API

The Data Catalog REST API defines a set of functions which developers/other tools can invoke via HTTP protocol. The requests and responses use JSON format (JavaScript Object Notation). In order to receive and send JSON media type, you should configure the HTTP client to include the Accept header (for receiving the data) and the Content-Type header (for sending the data):

Accept: application/json
Content-Type: application/json

Note

For simplification, the HTTP requests of this document only include relevant HTTP headers (other headers are omitted for simplicity). For example, the User-Agent header can have any value and it is not included in the examples.

The list of supported actions that you can execute using HTTP requests (GET, POST or DELETE), are the following:

All these API methods are stateless and they need to receive the user credentials each time to authenticate the user and then perform the requested action.

Log into the Data Catalog

The Data Catalog REST API supports two authentication methods: basic HTTP authentication and Single Sign-On authentication using Kerberos.

1. Login Using HTTP Basic Authentication

  • URL: /apirest/<op>

  • Method: GET

  • Required headers:

    • Authorization: basic HTTP authentication.
    • Accept: this header must include application/json media type in the list of supported formats.
Authorization: Basic <text>  /* base64 encoded of user:password */
Accept: application/json

The following example shows an HTTP request to perform method “synchronize” with the user admin with password admin:

GET /apirest/synchronize HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
Accept: application/json

{
    <ommited body>
}

If the user credentials are correct, Data Catalog processes the requested method with the attached body.

If the login request fails, the Data Catalog sends the HTTP error code 403 (Forbidden), with an empty body in its response.

2. Login Using Single Sign-On with Kerberos

  • URL: /apirest/<op>
  • Method: GET
  • Required headers:
    • Authorization: Kerberos token.
    • Accept: application/json media type must be included.
Authorization: <text> /* Kerberos Token */
Accept: application/json

The response types for the Kerberos authentication are the same as the response types for the basic HTTP authentication.

Synchronize Elements with the Server

You can synchronize the metadata defined in the Data Catalog with the metadata from the Virtual DataPort server by executing the following request:

  • URL: /apirest/synchronize
  • Method: POST

In the request body, you can choose:

  • To synchronize all the servers at once or just one of them.
  • Which types of elements (views and/or web services) you want to synchronize.
  • Which server has priority in case of conflict: the Data Catalog, the Virtual DataPort server or the Virtual DataPort server but keeping the local changes.

This way, the request body has to follow this format:

{
    "serverName": <text> | "allServers": "true",
    "type": "view | ws | all",
    "priority": "local | server | server_with_local_changes"
}

type and priority parameters are optional. If not specified, their default values are "type": "all" and "priority": "server_with_local_changes".

If the request has been successfully executed, the server sends the status code 200.

The response body includes the list of elements (views and/or web services) that have been synchronized (i.e. inserted, removed and modified) in JSON format.

{
    "result": "OK",
    "data": {
        "view": {
            "inserted": [<list_of_inserted_views>],
            "removed": [<list_of_removed_views>],
            "modified": [<list_of_modified_views>]
        },
        "ws": {
            "inserted": [<list_of_inserted_web_services>],
            "removed": [<list_of_removed_web_services>],
            "modified": [<list_of_modified_web_services>]
        }
    },
    "message": "OK"
}

The next example shows a POST request that synchronizes only the views from the server “localhost”, giving priority to the changes done in Data Catalog over the Virtual DataPort server:

{
        "serverName": "localhost",
        "type": "view",
        "priority": "local"
}

The response body contains the list of changed views:

{
  "result": "OK",
  "data": {
        "view": {
          "inserted": ["db.view-1", "db.view-2"],
          "removed": [],
          "modified": []
        },
        "ws": {
          "inserted": [],
          "removed": [],
          "modified": []
        }
  },
  "message": "OK"
}

In this example, the Virtual DataPort server contains two new views (db.view-1 and db.view-2), that from that moment will also be available in the Data Catalog.

Compute the Usage Statistics

If you execute a POST request to the following URL the Data Catalog computes and updates its usage statistics:

  • URL: /apirest/fetching-statistics
  • Method: POST

In the request body, you can choose to synchronize all the servers at once or just one of them.

{
    "serverName": <text> | "allServers": "true"
}

The next example shows a POST request to update the usage statistics of all the servers:

{
     "allServers": "true"
}

The response body contains the list of results by each server:

{
    "result": "OK",
    "data": {
        "responses": [
            {
                "serverName": "localhost",
                "serverUrl": "//localhost:9999/admin",
                "httpStatusCode": 200,
                "jsonResponse": {
                    "result": "OK",
                    "data": null,
                    "message": null
                }
            },
            {
                "serverName": "remote",
                "serverUrl": "//remoteHost:19999/admin",
                "httpStatusCode": 500,
                "jsonResponse": {
                    "result": "ERROR",
                    "data": null,
                    "message": "None of periods was chosen for statistics"
                }
            }
        ]
    },
    "message": null
}

In this example, statistics from server “localhost” were successfully computed, while in server “localhost2” there was an error, since it has no periods configured.