Create a New REST Web Method

The sub-branches beneath a newly created Web Service (as mentioned in Create a New Web Service - REST) allow you to create a Web Method.

To Add a New Web Method

Right-click on a sub-branch beneath a Web Service and select "Add Web Method" as shown below.

Adding a New Web Method

-OR-

Select a sub-branch beneath a Web Service, then click on the Add Web Method button, shown below, in the Edit section of the Home button in the Workbench.

Add Web Method button

This opens the Web Method properties in the right-pane of the Workbench as shown below. Enter a Namein the top text entry field.

General Settings Tab

This tab is used to configure common properties related to the Web Method.

General Settings

Description - Enter a description for the Web Method in the text entry field.
Relative URL - Enter a relative URL in the text entry field. The URL is relative to the parent Service’s Base URL.
HTTP Method - Use the pulldown menu to select from GET, POST, HEAD, PUT, DELETE, OPTIONS, PATCH, or MERGE.

Return Schema

Schema - Click on the Load Schema button to the right to autofill the field depending on the completed General Settings for the Web Method.
Return Value - With the Schema detected, use the pulldown menu to select from associated values. Selecting a property from the Return Value combo-box will pin the result of the Web Method Instance to that property, and everything at a higher level will be inaccessible.
Enable Dynamic Schema - Check when the JSON returned from the web method does not have a fixed schema.

When loading the schema of an API method, Workbench will call the method with the configured parameter values and analyze the result to understand the shape of the returned data. If the API returns an array, Workbench will look at the first item in the array and assume that all other items have the same schema. The data received from the service is anonymized and displayed in the Schema field.

Some APIs might return data that has a different schema depending on the parameters used for the call, or even an array of items that have different properties among different items. In such cases, the schema detection feature would not work because the schema is loaded once with the configured parameters and, for arrays, it is determined by looking at the first item of the array only.

The Enable Dynamic Schema checkbox can be used to support these scenarios: when dynamic schema is enabled, the Web Services runtime will determine the schema on the fly based on the current return value from the API. If the return value is an array with items having different properties, the Web Services runtime will generate the schema by merging all the different properties from the array items.

Note: dynamic schema is computationally more intensive, which may lead to reduced runtime performance. It is recommended to use it only when necessary, and to use fixed schema (by using the Load Schema button) in all other cases.

Parameters Tab

The Parameters tab allows to configure parameters for the Web Method.

Parameters Tab

Parameters

Click the "+ Click here to add new item" link to add a new default parameter. You can then enter a Name, Value, and Kind (using the pulldown menu, select from Query String or POST Body, Cookie, URL Segment, HTTP Header, Query String, or Request Body) and select whether the parameter will be Sensitive (by clicking the checkbox within that column).

When a parameter is marked as Sensitive, it will be obscured in the Workbench UI so that its value cannot be read. It will also be removed in runtime from the point name. For security reasons, unchecking the Sensitive checkbox will clear the parameter value.

As described above, the supported parameter types are:

Query String or POST Body. This selection allows to dynamically change how the parameter is sent to the service, depending on the HTTP method used for the call. If the call is made using HTTP GET, then the parameter will be sent in the query string. If the call is made using HTTP POST, then the parameter will be sent in the request body and the content-type of the request will be set to application/x-www-form-urlencoded. If the intent is to send a parameter always in the query string, then using Query String instead of this option is recommended.

Cookie. The parameter will be sent as a cookie with the specified name and containing the specified value.

URL Segment. This kind of parameter allows to dynamically replace a part of the request URL with the parameter’s value. For this to work, the URL must contain a placeholder in curly braces with the name of the parameter. For example, assume that the method’s relative URL is configured as:

api/v1/{endpoint}/

Creating a parameter called endpoint of type URL Segment will allow to dynamically specify the endpoint used in the URL for the request. In runtime, the placeholder in the URL will be replaced with the value of the endpoint parameter.

HTTP Header. The parameter will be sent as a HTTP header with the specified name, containing the specified value.

Query String. The parameter will be added to the query string of the request with the specified name, containing the specified value.

Request Body. This parameter type only applies to HTTP POST, PUT or PATCH. The parameter will be sent in the request body as-is, and the request content type will be set to the parameter’s name. Only one Request Body parameter is allowed. This kind of parameter is typically used to POST JSON payloads to a service, using application/json as the parameter’s name.

To simplify runtime usage, Request Body parameters also support virtual parameters. Consider the following example, where an HTTP POST is made to create a new social media post on an API:

Web Method to create a new post

Associated Request Body Parameter

Typically, a request body parameter will appear in the point name when browsed in runtime, carrying the whole JSON as its value:

Runtime Point Name with JSON

This leads to lengthy point names which are difficult to modify in runtime, especially when the JSON is complex.

With virtual parameters, it is possible to parameterize the Request Body so that only selected parts are changeable in runtime. Following the example above, assume we want to parameterize just the title and the body of the post that we want to create. We can go ahead and replace the values with a name of a parameter, prefixed with the special @ character:

Substituting virtual parameters in the Request Body

Then, we can proceed to create individual parameters for title and body, with Kind set to Query String or POST Body:

Creating Virtual Parameters

The final result is that in runtime, the Request Body parameter will not be a part of the point name anymore. We will see the title and body parameters instead:

Virtual Parameters in the Point Name

Data Refresh Tab

The Data Refresh tab is used to configure refresh behavior for the Web Method.

Data Refresh

Refresh Options

The Refresh Type combo-box allows to configure how the results received by the server are refreshed. The options are:

No Refresh. Once the result of a REST Web Method call is received by the Web Services runtime it is cached, and not requested again* from the REST Web Method.
Periodic. The result of a REST Web Method call is cached when received by the Web Services runtime, and it will stay cached for the amount of time configured by Refresh Period.
By Triggers. The result of a REST Web Method call is cached when received by the Web Services runtime, and it will stay cached until one of the Refresh Triggers fires.

*SeeHow the Web Services Runtime requests and caches data section for more details on how caching and requesting data from web services works.

Refresh Triggers

If a Refresh Type of "By Triggers" is selected, you can click on the + Click here to add new item link to create a new Refresh Trigger. Once activated, you can enter a Tag Name in the text entry field or click on the button to open the Data Browser and navigate to your selected Tag Name.

Once you have completed making edits to the Web Method Instance, click Apply to save your settings and Close to exit.

Multiple Triggers can be added to refresh the REST Web Method on different conditions.