Adding a REST Data Source

This section describes how to add a REST data source.

About POST and Multi-Part/Form

Multi-Part/Form supports the transfer of multiple binary types of data for POST operations. For example, you could use this to transfer multiple GIF files.

• For POST, the Multi-Part/Form option is enabled for an HTTP 'multipart/form-data' request.
• If the Multi-Part/Form option is chosen, each parameter that uses Body and 'IN' or 'IN/OUT' will be consumed as a string part of the request.
• If the Content-type parameter is defined for an HTTP header then the charset defined in the parameter will be applied to all parts for the request. The default charset is ISO-8859-1.

To add a REST data source

In Studio, right-click the folder in which you want to add the REST data source and choose New Data Source.
1. Select REST as the data source adapter and click Next.

Studio displays the New Physical Data Source dialog for you to define the REST data source.

2. For Name, enter a name for your REST data source.
3. On the Basic tab, provide this information for a REST data source:

Field

Description

Base URL

The base URL to access the REST data source. This is in the form:

http://<web site name>

Example: http://search.twitter.com
Use Metadata Check this option if you want to Introspect an Open API metadata document.
Metadata URL

When the Use Metadata option is selected, this field needs to be filled. Enter the location of the OpenAPI Metadata document that will be introspected.

Note:- Only primitive datatypes (non-structured) are supported.

Login

Optionally, provide a valid username to access the REST data source.

Password

Optionally, provide a valid password to access the REST data source.

Save Password

This check box is enabled only if Pass-through Login is enabled.

Pass-through Login

Disabled—The default setting. This allows automated provisioning of a connection pool. If Pass-through Login is disabled, the Save Password check box is not available.

Enabled—A new connection to the data source uses the credentials supplied by the client when data is requested from that data source for the first time. If Pass-through Login is enabled, the Save Password check box becomes available.

Refer the User Guide, Section About Pass-Through Login, for more information.

Authentication

Choose the method of authentication for this data source: BASIC, NTLM, or NEGOTIATE, OAuth, Digest.

When selecting OAuth as the authentication mode, another tab will display. Authentication for the data source must be designated as OAuth 2.0 when the physical data source was first added. For more information, see Client Authentication for Web Data Sources.

Domain

For NTLM authentication only. Enter the domain name.

See “Configuring NTLM Authentication” in the TDV Administration Guide for more information.

Service Principal Name

For NEGOTIATE authentication with Kerberos only: enter the service principal name.

See “Configuring Kerberos Single Sign-On” in the TDV Administration Guide for more information.

Access Token

For OAUTH 2.0 authentication, type the access token.
Automatically Retrieve Access Token Retrieve the access token automatically from the access token URL we mentioned in the OAuth tab

JSON Format

Check this box if you want to use the JSON (JavaScript Object Notation) standard for data interchange. When this box is checked, each HTTP request-response pair is encoded and decoded in the JSON format.

BadgerFish Enabled

Check this box to enable BadgerFish if the REST services outside of TDV use the BadgerFish convention to translate XML into the JSON format.

JSON Format must also be checked.

Primitive Value Format

Check this box to read and send the value in its primitive presentation.

JSON Format must also be checked.

Package Name

Prefix for each element to make the service name unique. The package name plays the same role as namespace in the XML format. Package name can consist of any characters that are legal in Java class names.

JSON Format must also be checked.

Wrapper of JSON Bare Response

Type in the wrapper name. It can be the wrapper key of the whole JSON response. This value makes it possible to convert JSON responses to well-formed XML value types.

JSON Format must also be checked.
4. On the bottom part of the Basic tab, define the REST operations.

Under Operations, click the Add Operation button to add an operation.

In the New Operation dialog box, enter a name for the operation and click OK.

For each operation, you must define an HTTP Verb and Parse an Operation URL.

Field

Description

HTTP Verb

Choose the operation type: GET, POST, PUT, or DELETE.

Operation Name

Automatically filled in with the operation name you entered and selected in the Operations box.

Operation URL

Enter the URL for the REST operation in the format:

<operation_api_name>?<query_parameters>
• <operation_api_name>—The API service operation name as defined by the URL. Examples: addfeed.atom and search.atom from Twitter. You need to know the operation names for your Web data source and follow their conventions.
• <query_parameters>—Separate multiple entries with & (ampersand). Can be one or more of the following:
• <constant>—Define one or more constants in the form constant=value.
Example: count=20
• <{URL_parameter}>—Define one or more URL parameters in curly brackets. Example: tweet={mytweet}

At execution time, the Base URL is combined with the Operation URL defined for each operation to form the data request.

Parse

Click Parse to add all URL parameters specified in curly brackets in the Operation URL to the URL Parameters list.

If the parser finds the syntax correct, it adds it to the URL Parameters list. For example, if you enter tweet={mytweet} in the Operation URL field and click Parse, mytweet appears under Param Name in the URL Parameters section.

For Request/Response Style, select one of the following:

Radio Button

Description

Bare

To support one parameter.

Wrapped

To support multiple parameters within a named wrapper.

For Wrapped only, enter:

• Request Wrapper QName—Specify a unique name for the parent element that is to contain the input parameters that you are wrapping.
• Response Wrapper QName—Specify a unique name for the parent element that is to contain the output parameters that you are wrapping.

Multi-Part/Form

To support the transfer of multiple binary types of data for POST operations. For example, you could use this to transfer multiple GIF files.

For URL parameters, you can edit parameters and their data types for those parameters that you are passing through the operation URL.

For Header/Body Parameters, define the header and body parameters and their information. If you want to use the design by example feature, you must save your data source definition to activate the Design By Example button. For more information on how to use this feature, see Using Design By Example to Infer Parameter Data Types.

— Click Add Operation to add a parameter. A new row appears in the Header/Body Parameters section with no name but with a default location (Body), data type (VARCHAR) and in/out direction (IN).
— Double-click under Param Name and type the name of the parameter.
— Click under Location, and from the drop-down list choose one of these options:

HTTP Header—Parameter is located in the HTTP header.

Body—Parameter is located in the body of the XML file.

— Click under Data Type, and from the drop-down list choose one of these options:

Option

Description

Decimal

DECIMAL, DOUBLE, FLOAT, or NUMERIC.

Integer

BIGINT, BIT, INTEGER, SMALLINT, or TINYINT.

String

CHAR, CLOB, LONGVARCHAR, or VARCHAR.

Time

DATE, TIME, or TIMESTAMP.

Complex

< >XML
Complex XML is any XML defined outside of the W3C XML standard. If your XML has customized elements or requires and XSD file to interpret the meaning of the XML elements within it, the XML is considered complex.

Browse

Choose this to browse for an XSD file that defines the data type being used.
— Click under In/Out, and from the drop-down list choose IN for input parameters or OUT for output parameters.
5. If the data source requires client authentication, click the Advanced tab. See Client Authentication for Web Data Sources for how to configure client authentication.
6. If the data source requires OAuth, select the OAuth 2.0 tab. Specify the values appropriate to the OAuth flow you want to use.

The following table describes the values the user is to provide on the OAuth 2.0 tab:

Field

Description

OAuth Flow

These OAuth flows:

• AUTHORIZATION_CODE
• IMPLICIT—Client Secret and Access Token URI are disabled.
• CLIENT_CREDENTIALS—Resource Owner Authentication fields are disabled.
• RESOURCE_OWNER_PASSWORD_CREDENTIALS—Client Authentication fields are disabled.
• CUSTOMIZED—User-specified flow.

Client Identification

Used in the request-body of token requests. A unique string representing the identifier issued to the client during registration. It is exposed to the resource owner. Format: string of printable characters.

Client Secret

Used in the request-body of token requests. Enabled only for AUTHORIZATION_CODE, and OAuth flow. Format: string of printable characters.

Authorization URI

URI to use for establishing trust and obtaining the required client properties.

Access Token URI

URI to use for communicating access and refresh tokens to the client or resource server. Disabled only for IMPLICIT OAuth flow.

Redirect URI

Client’s redirection end point, established during client registration or when making an authorization request. Must be an absolute URI, and must not contain a fragment component. The authorization server redirects the resource owner to this end point.

Scope

Authorization scope, which is typically limited to the protected resources under the control of the client or as arranged with the authorization server. Limited scope is necessary for an authorization grant made using client credentials or other forms of client authentication. Format: one or more strings, separated by spaces.

State

A request parameter used in lieu of a complete redirection URI (if that is not available), or to achieve per-request customization

Expiration Time (Sec)

The lifetime of the access token.

Use Refresh Token To Get Access Token

Checking this box enables the use of refresh tokens to obtain access tokens, rather than obtaining them manually.

Login and Password

User credentials with which the client or resource owner registers with the authentication server before initiating the OAuth protocol.

Pass-through Login

Enabled or Disabled

Authentication

BASIC, DIGEST, NTLM, or NEGOTIATE—The usual collection of authentication methods, used for registration with the authentication server.

Domain

Domain to which the client or resource owner belongs; for example, composite.

Service Principal Name

SPN of the client or resource owner.

Access Token Type

Bearer—User of a bearer token does not need to prove possession of cryptographic key material. Simple inclusion of the access token in the request is sufficient.

Query—The query string “?access_token=<token>” is appended to the URL. Not available for SOAP data sources.

Access Token

Credentials used to access protected resources, with a specific scope and duration. Usually opaque to the client.

Get Token button

Initiates acquisition of an access token. Proper information must be configured for this request to succeed.

Refresh Token

Credentials used to obtain access tokens when they become invalid or have expired. Intended for use with authorization servers, not resource servers.

Custom Flow

The name of the custom flow for a data source with an OAuth flow of CUSTOMIZED.

Using Processors check box

and editable text field

Check this box to use processors. The editable text field allows you to enter JavaScript and XML. You can use this field to add JavaScripts that log in automatically or use XML to customize any part of the authorization or access token that does not conform to specifications.

Editable text field

The editable text field underneath the Using Processors check box can be used to type the XML elements necessary to establish authorization and access tokens. For example:

<Authorization>  <AuthorizationProcessors>  
<AuthorizationProcessor>    document.getElementById('email').value='queenbeeza@gmail.com'; document.getElementById('pass').value='jellypassword'; document.getElementById('loginbutton').click();  </AuthorizationProcessor>  </AuthorizationProcessors>  </Authorization> 
<AccessToken> <RequestMsgStyle>QUERY</RequestMsgStyle> <ResponseMsgStyle>FORM</ResponseMsgStyle> 
<ExpireTime>1000</ExpireTime> </AccessToken>

Sensitive Keyword in JavaScript

Click the plus-sign icon one or more times to add tag-keyword pairs to substitute into the JavaScript specified for a custom authorization flow. The values sent to the server are encrypted, and then replaced with their decrypted values where the tags are found in the JavaScript.

These pairs are used for the user name, email ID, password, and other sensitive information.

Tag—The name of the tag to find in the JavaScript.

Keyword—The encrypted value to decrypt and substitute for the tag in the JavaScript.

 

7. Click Create & Close to save the REST data source.

Studio adds the REST data source to the resource tree and opens the Data Source Introspection window for you to introspect the new REST resource.

Passing JSON data to POST REST data source

The POST REST data source is most often configured to accept a set of the scalar parameter as inputs. Those inputs are then used to populate a POST request document. Using the REST data source, typically with a POST verb, parameters can be specified that encodes into the body of the request. Typically, the parameter name is used to delimit the parameter.

To pass a JSON data to POST REST data source:

Define your REST data source.
8. Select the checkbox next to the JSON Format label.
9. In the Basics tab, scroll further down to the Operations section.
10. Define the details for your operation, including the HTTP Verb, Operation Name, and Operation URL.
11. In the Header/Body Parameters table, add a Param Name named [rawdata] with a Data Type of varchar. This is a Body parameter of direction IN. [rawdata] is used to hold the JSON input payload.
12. In the Header/Body Parameters table, add a Param Name named Content-Type with a Data Type of varchar. This is a Body parameter of direction IN. When you run operation, set "Content-Type" to "application/json" which is the MIME type for json
13. In the Header/Body Parameters table, add a Param Name named response with a Data Type of the desired type. This is a Body parameter of direction OUT.

Examples

1. To create a datasource for a specific database adapter, path and properties:

JSON parameters:

data source bean list = [{"parentPath":"/shared/examples",  "name":"ds1", "adapterName":"PostgreSQL 9.1", "annotation":"This is a postgres datasource created using REST api", "nativeProperties":{"urlIP":"localhost", "urlPort":5432, "urlDatabaseName":"orders", "login":"tutorial", "password":"A49A5A0FAFF13F4A"} }]

Curl Invocation:

curl -X POST -u admin:admin "http://localhost:9400/rest/datasource/v1" -H "Content-Type:application/json" -d "[{\"parentPath\":\"/shared/examples\",  \"name\":\"ds1\", \"adapterName\":\"PostgreSQL 9.1\", \"annotation\":\"This is a postgres datasource created using REST api\", \"nativeProperties\":{\"urlIP\":\"localhost\", \"urlPort\":5432, \"urlDatabaseName\":\"orders\", \"login\":\"tutorial\", \"password\":\"A49A5A0FAFF13F4A\"} }]"

2. To create a sql script procedure with specified definition script:

JSON Parameters:

script beans = [{"parentPath":"/shared/examples", "name":"script1", "script":"PROCEDURE script1() BEGIN CREATE TABLE /shared/examples/ds_inventory/tutorial/sampleTable as select OrderId, ProductID, Discount, OrderDate, CompanyName, CustomerContactFirstName, CustomerContactLastName, CustomerContactPhone FROM /shared/examples/ViewOrder; END", "annotation":"This script is created using REST api"}]

Curl Invocation:

curl -X POST -u admin:admin "http://localhost:9400/rest/script/v1" -H "Content-Type:application/json" -d "[{\"parentPath\":\"/shared/examples\",  \"name\":\"script1\", \"script\":\"PROCEDURE script1() BEGIN CREATE TABLE /shared/examples/ds_inventory/tutorial/sampleTable as select OrderId, ProductID, Discount, OrderDate, CompanyName, CustomerContactFirstName, CustomerContactLastName, CustomerContactPhone FROM /shared/examples/ViewOrder; END\", \"annotation\":\"This script is created using REST api\" }]"