REST API

Starting with the update 8.0u20210715, the Data Catalog provides a REST API to perform programmatically all the tasks explained in this guide.

The documentation of this REST API is available on:

  • Starting with the update 8.0u20220126: http://<host>:<port>/denodo-data-catalog/swagger-ui/index.html

  • With the previous update (8.0u20210715): http://<host>:<port>/denodo-data-catalog/swagger-ui.html

Note

Previous versions of Data Catalog (7.0, 8.0GA and 8.0u20210209) provided a REST API to perform the following tasks:

  • Synchronize with Virtual DataPort

  • Compute the usage statistics

  • Export metadata

  • Import metadata

  • Ping

This legacy REST API is documented in the entries that start with legacy-. Take into account that it is only kept for backward compatibility, but it is deprecated. You should consider migrate to the REST API of the current Data Catalog 8.0.

Most of the endpoints in the REST API require authentication and you have to provide your credentials before accessing them.

The REST API support the following authentication methods:

  • HTTP Basic Authentication (stateless)

  • OAuth Token (stateless)

  • OAuth Token (stateful)

In the stateless authentication methods, you have to provide your credentials on every request. The credential could be the user name and password or an OAuth token.

In the stateful authentication methods, you have to provide your credentials only once. In this case, the server will generate a session cookie and an anti-CSRF token, that have to be sent in the next HTTP requests, in order to access the authenticated REST API endpoints.

If you have registered several Virtual DataPort servers in the Data Catalog, you must specify which one you want to connect to. Use the query parameter serverId with the internal identifier of the server as a value.

Note

You can obtain the internal identifiers of the Virtual DataPort servers registered in Data Catalog with the following endpoint of the REST API: /public/api/configuration/servers.

HTTP Basic Authentication (stateless)

The REST API supports the HTTP Basic Authentication method. Follow these steps to provide your credentials:

  1. Build the user-pass by concatenating the user-id, a single colon character (:) and the password.

  2. Encode the user-pass using Base64 into a sequence of US-ASCII characters.

  3. Build a header with the name Authorization and the value Basic <BASE64-user-pass>

The following example retrieves the information of the new home page of the Data Catalog authenticating with the user admin and the password admin:

curl --location --request GET 'http://localhost:9090/denodo-data-catalog/public/api/home' --header 'Authorization: Basic YWRtaW46YWRtaW4='

OAuth Token (stateless)

The OAuth 2.0 protocol is an open-standard protocol that allows client applications to access Denodo without sending the password of the user account.

Before using the OAuth 2.0 to access the Data Catalog REST API, you have to enable OAuth in Virtual DataPort.

Then, you have to include the access token in each HTTP request that require authentication. This token has to be included in the Authorization header:

Authorization header with Bearer OAuth token
Authorization: Bearer oauth_token

The following example retrieves the information of the admin database in the server with identifier “1”, using stateless OAuth token authentication:

curl --location --request GET 'http://localhost:8080/denodo-data-catalog/public/api/browse/databases?databaseName=admin&serverId=1' --header 'Authorization: Bearer oauth_token' --header 'Accept: application/json'

Note

This authentication method is disabled by default. To enable it, set the parameter oauth.statelessEnabled=true in the Data Catalog configuration file <DENODO_HOME>/conf/data-catalog/DataCatalogBackend.properties.

OAuth Token (stateful)

The OAuth 2.0 protocol can also be used as a stateful authentication method.

  1. Enable OAuth in Virtual DataPort.

  2. Invoke an endpoint that does not require authentication. This request will generate the initial session identifier and the initial anti-CSRF token. For example, you can use the /login/configuration endpoint that will return information about the available Virtual DataPort servers.

    curl --location --request GET 'http://localhost:8080/denodo-data-catalog/login/configuration' --header 'Accept: application/json'
    

    The response will contain the JSESSIONID cookie and the X-XSRF-TOKEN header. You have to extract this values and include them in the next request.

    HTTP/1.1 200 OK
    ...
    Set-Cookie: JSESSIONID=1234
    X-XSRF-TOKEN: abcd
    ...
    
    { ... <json response> ... }
    
  3. Invoke the /accesstoken authentication endpoint. This request has to include the OAuth access token. In addition, this request also has to include the cookie with the session identifier and the anti-CSRF token, both generated in the previous step.

    curl --location --request GET 'http://localhost:8080/denodo-data-catalog/accesstoken?serverId=1' --header 'Accept: application/json' --header 'Authorization: Bearer oauth_token' --header 'Cookie: JSESSIONID=1234' --header 'X-XSRF-TOKEN: abcd'
    

    The response will contain the new JSESSIONID cookie and also the new X-XSRF-TOKEN header. You have to extract them and use them in the next requests to the REST API.

    HTTP/1.1 200 OK
    ...
    Set-Cookie: JSESSIONID=5678
    X-XSRF-TOKEN: efgh
    ...
    
    { ... <json response> ... }
    
  4. Now, you can invoke the REST API endpoints using the JSESSIONID cookie and the X-XSRF-TOKEN header, both generated in the /accesstoken response. The following example retrieves the information of the admin database in the server with identifier “1”

    curl --location --request GET 'http://localhost:8080/denodo-data-catalog/public/api/browse/databases?databaseName=admin&serverId=1' --header 'Cookie: JSESSIONID=5678' --header 'X-XSRF-TOKEN: efgh' --header 'Accept: application/json'
    

Note

This authentication method is disabled by default. To enable it, set the parameter oauth.statefulEnabled=true in the Data Catalog configuration file (<DENODO_HOME>/conf/data-catalog/DataCatalogBackend.properties).

CORS configuration

In order to access the REST API of the Data Catalog from a cross-site environment, you must configure the Denodo Platform as follows:

  1. Do the steps of the section Initial Set-Up of CORS (you have done this already if you published a Denodo REST web service with CORS enabled).

  2. Before starting any server of this Denodo installation, edit the file <DENODO_HOME>/resources/apache-tomcat/conf/context.xml and change the default policy for the SameSite cookies to this:

    <CookieProcessor sameSiteCookies="none" />
    
  3. In the configuration file <DENODO_HOME>/conf/data-catalog/DataCatalogBackend.properties add or edit the property cors.enabled and set to true. To disable CORS, remove the property or set to false. In this file you can also set the following optional properties to fine-tune the CORS configuration:

    • cors.allowedOrigins: set a list of origins allowed to execute cross-origin requests (separate each origin by a space). For example, cors.allowedOrigins=http://localhost:3000 https://localhost:3000. By default, the value of the property cors.allowedOrigins is *. This means that any domain can execute cross-origin requests.

    • cors.allowCredentials: if is set to true, the client will expose the response credentials to frontend JavaScript when the request’s credentials mode is include. By default, the value of the property cors.allowCredentials is true.

    • cors.allowedHeaders: set a list of HTTP headers that can be used in cross-origin requests (separate each HTTP header by a space). For example, cors.allowedHeaders=content-type uri x-xsrf-token. By default, the value of the property cors.allowedHeaders is *. This means that cross-origin requests can use any HTTP header.

    • cors.allowedMethods: set a list of HTTP methods allowed in cross-origin requests (separate each HTTP method by a space). For example, cors.allowedMethods=GET POST PUT DELETE. By default, the value of the property cors.allowedMethods is *. This means that cross-origin requests can use any HTTP method.