Publishing a REST Service

This section describes how to add a REST-compliant data service. The configuration steps are optional.

• Configuration Options for Publishing a REST Service
• Publishing a REST Data Service

Configuration Options for Publishing a REST Service

This setting determines whether to enclose an XML output parameter with a wrapper element in a TDV REST Web Service when the parameter is a generic XML type.

To configure XML output parameter wrapper elements

1. From the Administration menu, choose Configuration.
2. Search for or navigate to the Generic XML REST Output Parameter Wrapper parameter.
3. Set the value to False to exclude the wrapper element, or set the value to True to include the wrapper element.
4. Stop and restart the TDV server to ensure that the parameter value change is recognized.
5. Make sure that the procedure that you define has a variable of data type ‘XML’.

For Example

Assume that the Output parameter for the following code snippet is cust_data and that the data type is a generic XML type. 

<ns1: cust_addr>
<mail_addr>
. . .
</mail_addr>
</ns1:cust_addr>

Set the Generic XML REST Output Parameter Wrapper parameter to true, to obtain output similar to:

<cust_data>
<ns1: cust_addr>
<mail_addr>
. . .
</mail_addr>
</ns1:cust_addr>
</cust_data>

If you do not want the parameter name wrapper in your output, set the configuration parameter to false. For example:

<ns1: cust_addr>
<mail_addr>
. . .
</mail_addr>
</ns1:cust_addr>

Publishing a REST Data Service

To publish a REST data service

  1. Select the Web Services node under the Data Services node in the Studio resource tree.

  2. Right-click and select New Composite Web Service.

  3. For Data Service Name, enter a name for your Web service.

  4. Click OK.

  5. From the resource tree, open the data service that you just created.

    By default, the SOAP tab is displayed.

  6. Optionally, publish views and procedures to the Web service:

    Select one or more tables, view, or procedure from the resource tree, and right-click.

    Select Publish.

    In the Publish window, type the name to use for the published resource.

    Select the Web service to which you want the resource to be published.

    Click OK.

  7. Select the REST tab.

  8. In the Service portion of the screen, type or select values for the following properties.

If the property has a default value, a value is required.

Property

Required

Description

Enable

Yes

True (the default) tells the system you want to use the information defined on this tab.

Target Namespace

Yes

Replace the default value with the location of your REST installation.

Service Name

Yes

The name to give your service.

Enable SSL/TLS

Yes
• Require SSL/TLS — True/false
• Require Client Certificate — True/false

SSL uses digital certificates, trusted certificate authority (CA), and encryption keys.

When this is set to true, HTTPS/JSON and HTTPS/XML endpoints URLs are added to the Property list in the lower part of the Operations section.

JSON Context Url Pat

 

Default value is /json.

XML Context Url Path

 

Default value is /xml.

JSON Format

Yes for JSON
• JSON Package Name — Default name of your JSON service. The input and output data use this package name.
• Use Parameter Name of Procedure— If true, a JSON object name with the format of parameter will be the same as the original name defined in the procedure. The default value is false. If false, the format is: 
<package name> + '.' + <procedure name>+<parameter name>
• Validate XML Schema Definition Set - The default value is true. This option works in streaming mode with XML/JSON conversion and validate JSON response structure with XML definition set for XML values, will get empty or part of data if validation fails. Set this option as "false" still could get correct Json response data.
• Wrapped Cursor—If true, a JSON row object is added as a wrapper of the cursor output, for tables and procedures.
• Wrapped Table—If true, the table output is wrapped with an output JSON object with a pattern of: 
<package name> + '.' + <table name> + 'output'

For the wrapped options, the default value is true. Default value is consistent with an XML definition.

Enable HTTP Basic

Yes

Valid values are true or false. Set to true to enable a method to provide a username and password (when making a request) that results in a string encoded using a Base64 algorithm.

Enable HTTP Bearer

No

Valid values are true or false. Set to true to enable OAUth2 token based authentication. over HTTP.

Enable HTTP NTLM

No

Used to enable NTLM authentication over HTTP.

Enable HTTP Negotiate

No

Used to enable Kerberos and Active Directory authentication over HTTP.

  1. From the upper part of the Operations section, select a Web service view or procedure that is available for use.

    If you publish a new view or procedure to the Web service while this window is open, you might need to close and reopen this window for it to appear in the list.

  2. In the lower part of the Operations section, type or select values for the properties listed in the following table.

Property

Description

HTTP Method

Select the verb associated with the procedure, for example GET, POST, PUT, or DELETE. Depending on the choices you have made for the operations field, these options might already be defined.

Operation URL Path

Specify the operation URL path as defined for your operation. Follow endpoint URL guidelines to configure your values. You can use brace tags.

You can specify a portion of the endpoint URL to be used in each Web service module. In a published WSDL file, the URL defining the target endpoint address is found in the location attribute of the port's soap:address element.

Input Message

 

Parameter Style

Use this field to determine the shape of the input argument or message. This value applies to all parameters.

• Select WRAPPED when there might be multiple parameters that use the BODY location. The wrapper element is the child of the REST BODY and the parameter elements are children of the wrapper element.
• Select BARE when exactly one parameter has a location of BODY and its element is the only child of the REST BODY. All other parameters of the same direction must be mapped to another location—for example, HEADER.

 

Wrapper

 

 

Element Name

Unique name for the wrapper element. For example, if you type wrappedOrderParams here, the WSDL XML includes an element:

<wrappedOrderParams> </wrappedOrderParams>

 

Element Type

This is the type value of your row element.

Output Message

 

Parameter Style

The value applies to all parameters.

• Select WRAPPED when there might be multiple parameters that use the BODY location. The wrapper element is the child of the REST BODY and the parameter elements are children of the wrapper element.
• Select BARE when there is exactly one parameter with a location of BODY and its element is the only child of the REST BODY. All other parameters of the same direction must be mapped to another location, for example, HEADER.

 

Wrapper

 

 

Element Name

Unique name to give to the wrapper element. For example, if you type wrappedOrderParams here, the WSDL XML includes an element:

<wrappedOrderParams> </wrappedOrderParams>

 

Element Type

This is the type value of your row element.

Endpoint URLs

 

HTTP/JSON

Displays the HTTP/JSON endpoint URL for this operation.

 

HTTPS/JSON

Displays the HTTPS/JSON endpoint URL for this operation. Present only if Enable SSL is true in the Service section of this panel.

 

HTTP/XML

Displays the HTTP/XML endpoint URL for this operation.

 

HTTPS/XML

Displays the HTTPS/XML endpoint URL for this operation. Present only if Enable SSL is true in the Service section of this panel.

  1. Save your settings.

  2. Repeat the steps in Publishing a SOAP Data Service for each operation or view you want to define for the Web service.

  3. If your operation has parameters, go to the Parameters portion of the screen and select a parameter from the upper list.

  4. In the lower part, type or select values for the following properties for input or output parameters.

Property

Resource Type

Description

Name

All

Name of the parameter. Cannot be edited.

Row Element Name

Table
View

Fully qualified name to give to the input parameter, output parameter, or output cursor; or name (relative to the cursor path) to give to the column.

Row Type Name

Table
View

(Cursor only) Type value of this row element.

Cursor Type Name

Table
View

(Cursor only) Unique name for the type that defines the global cursor element.

Element Name

All

Can be NULL. The default value of the Element Name field specifies the schema of the REST message that is encrypted. This procedure can be used to encrypt the REST message body.

Binding Location

Procedure

When the selected operation is a procedure, you can define binding locations. If the message is BARE, exactly one parameter must use the BODY binding location.

The available locations for input are:

ENTITY (not available for GET), QUERY, HEADER

The available locations for output are:

ENTITY

Query

Procedure

The parameter-name part of a query string. The query argument can accept NULL values. For example, the following query arguments are both valid:

• http://localhost:9410/json/goody/data?name_arg={name_arg_value}
• http://localhost:9410/json/goody/data

Default Value

Procedure

Optional. Default value to use for the parameter if a parameter value is not passed through the request.

Nullable

Procedure

Whether this field is allowed to have no value. True specifies that the parameter can be passed to the server with no value. Without a value for the parameter, all data is returned from the query.

Element Name

Procedure

Can be NULL. The default value of the Element Name field specifies the schema of the REST message that is encrypted. This procedure can be used to encrypt the REST message body.

Direction

All

Indicates the direction of the input parameter, output parameter, or output cursor. Cannot be edited.

  1. Repeat the steps for each parameter to be defined for the Web service.

  2. Save your definition.

Accessing the Published REST Services

TDV provides Open API compliant specifications for all the published REST services. To access this tool, open TDV Studio and click on Help -> Published REST Web Services menu item. You can also access the specification using the url: http://localhost:9400/rest/api-docs/webservice.html

Using this tool, the users can get the response schema and verify that it is as expected.

Note: The users can only see the published REST services that they have READ privileges for.