REST Services Source

In the PIP Settings UI you will create a new data source, give it a unique name, and choose the 'REST' adapter.

Configuring the REST Service Data Source

To configure a data source:

1. Open the Tenant Settings screen and select PIP Settings.

2. In the Policy Authorization Group drop-down menu, select a PAA from the list of available PAAs. The Data Source List and Views List for the selected PAA is displayed.

3. Click New Data Source.

4. In the Data Source Details section:

   • Enter the Display Name for the new Data Source.
   • In the Connection Adapter field, in the Webservice section, select REST.

5. In the Connection Settings section under Policy Authorization Agent, select a PAA and then:

   • In the End Point field, enter your REST service endpoint base URL. For example, https://domain.com/data.
   • If your REST services use security, select the Security Type (for example: Httpbasic, Kerberos, OAuth). For OAuth, see OAuth Authentication Support.

6. In the Models section, create a new model and give it a unique name.

7. Under the DDL section, write a valid DDL to fetch REST attributes according to the REST service response. Here are some guidelines to help you create a DDL for REST service:

   • The general structure of the DDL is as follows:

 CREATE FOREIGN TABLE <Virtual_Table_Name>(

     <Attribute_Name> <Data_Type>,

     <Attribute_Name> <Data_Type> options (nameinsource '<relative JsonPath to the location of the field in the response>')

 ) OPTIONS (nameinsource '<JsonPath to the root location in the response>', "plainid:method" 'GET', "plainid:URI" '<ENDPOINT_URI_AFTER_BASE_URL>', "plainid:unwrap" '<True/False>');

• The structure of this DDL includes the declaration of the table, declaration of all attributes, and a general options clause.

Example:

  CREATE FOREIGN TABLE test (

      uid string,

      EntID string options (nameinsource 'Ent[*].id')

  ) OPTIONS (nameinsource '$', "plainid:method" 'GET', "plainid:URI" 'rest-test/getEntInFlight/UserID/$(uid)/', "plainid:unwrap" 'true');

Available OPTIONS in the DDL

Translator Properties

Supportsfilter

When using dynamic parameters in the forms of $(attribute) in the URI, a dynamic header, or JSON option, the supportsfilter property is mandatory and can be set to:

• true: Filters are sent to the REST Data Source according to the Dynamic Parameters in the REST definition. After retrieving the data back from the REST endpoint, no additional filtering will occur, the data is considered as authorized, and is sent back to the requesting service (i.e. the PDP).

  • The advantage of the true setting is that users can leverage the Data Source filtering capabilities by applying Dynamic Parameters and reducing the overall performance and payload with a smaller and filtered dataset.

  • The drawbacks of this setting is that filtering is limited to the REST endpoint functionality, so only supported filters will be applied on the query. The REST Data Source needs to support all needed filters to avoid fetching unauthorized data.

• false: Filters will not be transmitted to the REST Data Source. Instead, the data is fetched according the the REST definition without any dynamic filters. After the data is retrieved, the PIP settings applies filters to the dataset based on the incoming SQL query, and only then is the filtered data sent back to the requesting service (i.e. the PDP).

  • The advantage of false setting is that filters can vary and can be dynamically updated as the filtering takes place at the SQL level in PIP service.

  • The drawbacks of the setting is that it is required to fetch larger datasets (potentially all datasets) from the REST datasource to the PIP service, which can cause big payloads and performance issues.

Note: If this property is not sent, the default is false.

Multi-value Parameters

When a multi-value attribute passes in the query, all the values are used in the dynamic parameters injected into the REST request.

Examples:

POST {
  "paramA": [
    "a1",
    "a2,
    "a3"
  ]
}

GET ../../..?paramA=a1,a2,a3

To partially filter the REST Data, refer to the section on Partial Filtering. You cab also check out the Data Source Filtering Parameters section for more information on how to filter data sources.

Headers

You can use the headers property if you need to inject custom headers into the REST request that will be sent. The value is a JSON containing a list of headers, for each the header name and an array of values in this form:

• {"x-header1": ["value1", "value2"] ,"x-header2": ["value1", "value2"]}

• Note that if you need to use X-Auth-Token to authenticate your REST endpoint, you can add the property ‘headers’ with the value{"X-Auth-Token":["<token>"]}.

Dynamic Headers

• When configuring headers in the translator property, users can optionally adjust dynamic header values denoted by $(<attribute_name>). For example, the structure of a header setup could be similar to the existing one: {"x-header-accountID":["$(accID)"]}. In this setup, $(accID) would be replaced with the value sent by runtime during the preparation of the REST request.

• It is important to note that if the value of the dynamic parameter $(<attribute_name>) is null or empty (not sent in the runtime request), the corresponding header should be skipped instead of being sent empty.
  Note: Make sure the supportsfilter is set to true when setting up dynamic headers.

Partial Filtering

When using the above mentioned supportsfilter property you need to instruct the PIP that not all filters were pushed down to the REST Data Source, therefore further filtering of the fetched data is required. To support this scenario, you can use the supportsPartialFiltering translator property.
​
When setting this property to true (false by default) you also need to add an additional option for each attribute you want to further filter after getting the response from the REST Data Source. The additional option is "teiid_rel:partial_filter" 'true' that should be added to the options section:
attributeA string options (nameinsource '<option value>', <option x> '<option value>', "teiid_rel:partial_filter" 'true').

Data Source Filtering Parameters