REST Connectors

1. Go to Projects.
2. Select a project and click Connectors > REST. The REST Connectors page appears to list all custom REST connectors created.

Connector

A component or module that allows interaction with an external API by handling authentication, making requests, and processing responses.

REST (Representational State Transfer)

An architectural style that is used for designing networked applications. It uses standard HTTP methods (such as GET, POST, PUT, DELETE) and is based on stateless communication between client and server. REST connectors enable interaction with any external REST APIs, whether they are internal systems, third-party services, or cloud applications.

Client/server Architecture

REST uses a client/server model where the client and server are separate entities. The client makes requests, and the server processes them and returns the appropriate responses.

Statelessness

Each request from a client to a server must contain all the information that is needed to understand and process the request. The server does not store any state between requests.

Pre-built REST connectors

A set of predefined connectors provided by the IBM webMethods Integration platform for services like Salesforce, Google, and others.

Custom REST connectors

Connectors that are created by you by providing the necessary API details (URL, headers, authentication methods, and so on) for any REST API you want to connect to.

Uniform Interface

RESTful services have a consistent, standardized way to interact with resources, typically by using URLs to represent entities and HTTP methods to do operations on them.

Resource

A data entity or object that the API shows (for example, users, orders, products). Each resource is identified by a URL, and clients interact with resources by using standard HTTP methods to do operations on them.

REST Action

Represents a specific operation or endpoint within a RESTful API, typically corresponding to a Create, Read, Update, Delete (CRUD) operations. The structure of a REST action consists of several key components. These include HTTP Methods, Headers, Request, Response, Parameters, and Error Handling. These components define how the action is done and what data is involved.

Method (HTTP Method)

The type of operation to do on a resource such as

• GET - Retrieves data from the server.
• POST - Submits data to the server, often to create a new resource.
• PUT - Updates an existing resource or creates it if it does not exist.
• DELETE - Removes a resource from the server.
• PATCH - Partially updates a resource.

API URL or Endpoint

Full URL that you use to make the API request, which includes both the base URL and the resource path, for example, https://rest.example.com/users/123orders. It is the login endpoint URL to initiate communication with the SaaS provider. To get the endpoint, go through the SaaS provider documentation available on the internet.

Base URL or API Server URL

The root URL of the API that typically includes the domain and any base path, for example, https://rest.example.com/.

Resource path

Part of the URL that specifies the resource and how it is structured, for example, /users/{user_id}, /orders.

Parameters

Values that can be passed with a request to modify the behaviour or specify criteria for the request. These parameters help the server process the request and return the correct response. Parameters are of several types such as path parameters, query parameters, or header parameters.

Path Parameters (URL parameters)

Dynamic values within the URL path that are replaced with actual values to specify a particular resource. Path parameters are placed in the URL directly within curly braces {}. For example, /users/{user_id}, where {user_id} is the dynamic value that indicates the user’s ID.

Query Parameters

The key-value pairs that are appended to the URL to filter, sort, or paginate data in a REST API request. These parameters are appended to the URL after a ? symbol and multiple parameters separated by &. For example, /products?category=electronics&sort=price.

For example, an API resource path with a base URL, endpoint path, path parameters, and query parameters is explained as follows.

Full Resource Path - https://rest.example.com/users/{user_id}/orders?status=shipped&sort=date&page=2&limit=10

Explanation

• Base URL - https://rest.API.com is the root URL of the API.
• Endpoint Path - /users/{user_id}/orders specifies that you are accessing the orders of a specific user. The {user_id} is a path parameter that is replaced with an actual user ID, for example, /users/123/orders.
• Path Parameter - {user_id} is replaced by the actual ID of the user whose orders you are querying, for example, /users/123/orders.
• Query Parameters - ?status=shipped&sort=date adds filtering and sorting options to the request. Here, status=shipped filters orders that are marked as shipped, sort=date sorts the results by the order date, page=2 retrieves the second page of results, and limit=10 limits the response to 10 users per page.

So, an actual request looks like, https://rest.example.com/users/123/orders?status=shipped&sort=date

Form Parameters

Form parameters are used to submitt form data, commonly with POST, PUT, or PATCH requests and are passed in the request body. They are key-value pairs and can be transmitted in formats like application/x-www-form-urlencoded (standard form) or multipart/form-data (for file uploads).

POST https://rest.example.com/v1/users

Name=John+Doe&email=john.doe %40example.com&age=30

Authentication

The process of verifying the identity of the user. Every Saas provider has their own authentication mechanism to provide authorized access to its APIs. You need to get the authentication details from the SaaS provider documentation. For example, for Twitter, go to https://apps.twitter.com and then get the credentials. For Twitter, the authentication is OAuth V1.0a, which you can get from https://apps.twitter.com.

Common methods that are supported are,

• Credentials - Basic authentication that uses a username and password for access to the REST connector.
• OAuth V1.0a - An older version of OAuth that uses request tokens and access tokens for secure API authentication.
• OAuth V2.0 - A more secure and flexible version of OAuth that uses access tokens for authorization, commonly used in modern web and mobile applications.
• OAuth V2.0 (JWT Flow) - A variant of OAuth V2.0 where JSON Web Tokens (JWT) are used for secure token exchange in the authorization process.
• AWS S3 Signature - Authentication that uses AWS S3-specific signature to authenticate requests to Amazon S3 storage services.
• AWS V2 Signature - The signature version 2 of AWS, used for signing requests to AWS services, particularly for legacy integrations.
• AWS V4 Signature - A more secure, current version of AWS signature used for signing requests to AWS services, for better protection of sensitive data.
• OAuth V2.0 (JWT Client Assertion Flow) - A flow in OAuth V2.0 that uses JWT client assertions to authenticate a client, and makes sure of secure API access without exposing credentials.

Note:

Currently, IBM webMethods Integration supports the OAuth V2.0 (JWT Client Assertion Flow) authentication method exclusively for Microsoft endpoints. Know more about the OAuth V2.0 (JWT Client Assertion Flow) authentication method.

Headers

Key-value pairs are included in the request or response to provide additional information or control the behavior of the request or response. Header parameters are typically used for authentication, content type specification, and caching. Common headers are,

• Authorization - Used to send credentials, for example, Bearer token.
• Content-Type - Specifies the type of data being sent, for example, application/JSON.
• Accept - Specifies the expected response format, for example, application/JSON.
• User-Agent - Describes the client making the request, for example, a web browser or mobile app.

Body

The content sent with requests, typically in JSON or XML format, that contains the data to be processed by the API. This is typically used with methods like POST, PUT, and PATCH where data needs to be sent to the server to create, update, or modify resources.

For example, a request body with parameters like name, email, and age that the server uses to create a new user is as,

POST https://rest.example.com/v1/users
Content-Type: application/json
{
  "name": "John Doe",
  "email": johndoe@example.com,
"age": 30
}

Response

The data returned by the API after processing a request, often in JSON or XML format. The response includes a status code indicating the success or failure of the request and results in the response body.

Response Body

The body often contains the requested data or a message about the result, typically in JSON or XML format. For example, the response body containing parameters like ID, name, and email of the user is as

GET https://rest.example.com/v1/users?(123)
 Content-Type: application/json
 { 
“userId”: “123”, 
“name”: “John Doe”,
“email”: “johndoe@example.com” 
}

Status Code

A numeric code returned by the API to indicate the outcome of the request, for example,

• 1XX - Informational
• 2XX - Success
• 3XX - Redirection
• 4XX - Client error
• 5XX - Server error

Rate Limiting

A technique to limit the number of requests an API client can make within a certain time frame to prevent abuse and ensure fair usage.

Timeout

The maximum time the client is willing to wait for a response from the API server before generating an error.

Webhooks

A method for APIs to send real-time notifications to external services when certain events occur, for example, sending an email when a new order is placed.

API Key

A unique identifier used to authenticate requests to an API, often included in request headers or as a query parameter.

Proxy

A server that acts as an intermediary between a client and the target API, often used to improve performance or handle security and routing.

Payload

The data is sent in the body of a request (typically for POST and PUT requests) or response.

Callback URL

A URL provided by the client where the server will send responses or notifications after completing a process (common in OAuth flows).

Swagger or OpenAPI

A specification for describing RESTful APIs, often used to auto-generate API documentation and client libraries.

JSON or XML Format

REST APIs typically exchange data in a lightweight format like JSON (JavaScript Object Notation) or XML (eXtensible Markup Language), with JSON being more commonly used due to its simplicity and ease of integration with modern web technologies.

API Specification Type

An API specification type is a standardized format or framework that is used to define and describe the structure, behaviour, and interactions of an API. It outlines how the API must be used, including details such as endpoints, request response formats, methods, and parameters. Common API specification types include OpenAPI, RAML, GraphQL SDL, WSDL, and AsyncAPI, each serving different API styles (such as REST, SOAP, or GraphQL) and use cases. These specifications help ensure consistent API design and provide clear documentation for developers.

The approaches to create custom REST connector are,

• Automatic
  • Import from URL - Directly import a Swagger or Open API specification file to create a REST connector. You can either configure the connector settings or use it as-is.
  • Import from local file - Import a YAML or JSON file to create a REST connector. The file must adhere to Swagger or OpenAPI specification standards. You can either configure the connector settings or use it as-is.
• Manual
  • Create new - Build a connector from scratch by defining all necessary resources, such as HTTP methods and parameters, for proper functioning of the REST connector.

Each approach provides flexibility in configuring the connector settings, and you can either fine-tune the configuration or use the default setup as is. Choose the approach that best suits your preferences and available resources.

Custom REST Connector Creation - A Comparison of Approaches

While using automatic approach to create the connector,

• The guidelines followed to derive the Content-Type and Accept header are as follows:
  • "application/json" is the default selection if found in the list.
  • Else, the first one from the list is selected.
    • if the first one is found as "*/*", then the next one is selected if present.
    • if only "*/*" is found, then the default is set to "application/octet-stream".
  • The response Content-Type header value is set as the request Accept header.
    • No interactions are created for the deprecated operations.
    • For the OpenAPI version 3 specification, operations with "application/x-www-form-urlencoded" & "multipart/mixed" are not supported.
    • "multipart/form-data" is not supported.
    • You cannot create or edit any operation using the New Operation option in the Custom Operations page.

1. Go to the Add REST Connector wizard. See, Accessing Custom REST Connector Wizard.
2. In the Select source page, select Import from URL. The fields to configure the connector details appear.
3. Enter the following details under the Import from URL section.
   • API URL - Endpoint URL for the connector, consisting of a base URL, a specific endpoint, and query parameters (optional) . For example, https://rest.example.com/users/.
   • API Type - Framework used to define and describe the structure, behavior, and interactions of an API. For example, Swagger or OpenSpec.
   • API server URL - Base URL of the server hosting the API. This is automatically generated from the API URL field. For example, https://rest.example.com/.
4. Click Next. The Configure Connector Info page appears.
5. Configure the connector details:
   • Name - Name for your connector, for example, MyCustomAPI.
   • Icon - Browse and select an icon for the connector, if necessary, by clicking Update .
   • Authentication type - Choose the appropriate authentication type for the connector.
   • Description - A short description for the connector.
6. Click Next. The connector is created and the Configure action page appears. The actions that are defined in the file or URL are automatically generated and displayed on the left side of the page. The details of the selected action are shown on the rest of the page. The details are grouped based on the components.
   Note: You can click one of the following buttons to,

   • Discard Import - The connector creation is stopped, and you are directed to the Select source page.
   • Cancel - The connector creation is stopped, and you are directed to the REST Connector page.
7. Update the connector actions (if applicable) by clicking Add in the respective grouping for request and response.
   • Parameters - Define any query parameters that must be included in the request.
   • Headers - Specify any necessary headers, for example, Authorization, Content-Type.
   • Body - If the operation involves sending data, for example, POST or PUT, define the body format (JSON, XML, and so on).
   • Click Update Action. The actions are updated.
8. Click Finish. The Connector Info page appears.
9. If you want to modify, click Edit and update the connector information.
10. To view any action information,
    1. Select any action. The action details appear.
    2. Click Edit to modify the action details and click Update to save the changes.
    3. Click i/o to view the input and output signature that is defined for an action.
    4. Click Test to test the specific action. To test, you must have an account. For more details on creating an account, see To configure an account for the REST connector.
11. Test the Connector

    Before finalizing the connector, you can test it using the Test functions to ensure that it works as expected.

    1. To test, you must have an account. For more details on creating an account, see To configure an account for the REST connector.
    2. Perform any connector action and verify the response.
    3. If you want to modify, click Edit, make changes and click Update to save the changes.

1. Go to the Add REST Connector wizard. See, Accessing Custom REST Connector Wizard.
2. In the Select source page, select Import from File. The fields to configure the connector details appear.
3. Enter the following details under the Import from File section:
   • Upload File - Browse and select the file that contains the connector details.
   • API Type - Framework used to define and describe the structure, behavior, and interactions of an API. For example, Swagger or OpenSpec.
   • API server URL - Base URL of the server hosting the API. This is automatically generated from the API URL field. For example: https://rest.example.com/.
4. Click Next. The Configure Connector Info page appears.
5. Configure the connector details:
   • Name - Name for your connector, for example, MyCustomAPI.
   • Icon - Browse and select an icon for the connector, if necessary, by clicking Update .
   • Authentication type - Choose the appropriate authentication type for the connector.
   • Description - A short description for the connector.
6. Follow the instructions from Step 6 mentioned in Create Custom REST Connector from a URL.

1. From the IBM webMethods Integration navigation bar, click Projects.

2. Select a project and then click Connectors > REST > Add Connector.

3. In the Define Connector page, complete the following fields.

   Note: Required fields are marked with an asterisk on the screen.
   • Name: Type a name for the REST connector. For example, `ExternalRESTapi`.
   • Description: Type an optional description for the REST connector. The description you enter here will appear on the Connectors page.
   • Authentication Type: Every back end provides its own authentication mechanism. Get the authentication details from the back end documentation and select the supported authentication type from the drop-down list. REST connector supports the following authentication types:
     • Credentials
     • OAuth V1.0a
     • OAuth V2.0
     • OAuth V2.0 (JWT Flow)
     • AWS S3 Signature
     • AWS V2 Signature
     • AWS V4 Signature
     • OAuth V2.0 (JWT Client Assertion Flow)
       Note: Currently, IBM webMethods Integration supports the OAuth V2.0 (JWT Client Assertion Flow) authentication method exclusively for Microsoft endpoints. For more information, see the OAuth V2.0 (JWT Client Assertion Flow) authentication method.
       Important: When you select Authentication Type as Credentials, the system displays a new configurable field, Preemptive Auth, during account creation, with a default value of true. You can change the value of this field as per your specific use case.
   • Default Endpoint URL: Specify the endpoint URL for the connector. It is the login endpoint URL to initiate communication with the SaaS provider. For example, "http://dummy.restapiexample.com/api/v1".
     Note: If you are using the OAuth V2.0 (JWT Client Assertion Flow) authentication method, ensure that the default endpoint URL for the REST connector is exclusively for Microsoft endpoints. For example, "https://graph.microsoft.com/".
   • Connector Icon: Click Browse and select another icon for the REST connector, if necessary.

4. Click Next. The Resources page appears.

5. Click Add Resource.

   On the Add Resource page, complete the following fields:

   • Name: Type the resource name. For example, getEmployeeList.
   • Path: Type the path for the Resource. The Resource path is relative to the endpoint specified. Each REST Resource derives its path from the namespace of the REST Resource. For example, if the REST Resource is named getEmployeeList, the path is /employees. You can define dynamic parameters in the resource path by enclosing each parameter within { } brackets. For example, to get the employee data corresponding to a dynamic parameter called employeeID, specify the source path as /employee/{employeeID}. To get the item information from a particular department in a store, specify the resource path as /store/{departmentID}/{itemID}.
   • Methods: Every Resource must have a method associated with it. Select an HTTP Method, for example, GET for get actions.
     Note:

     • While adding Methods, if the Resource path contains { } brackets, for example, /user/{userID}, you must add a request parameter having the same name, that is, userID, and set the Parameter Type to URI_CONTEXT.

     • When a resource's URL is updated, the associated operations must also be edited and saved to ensure the new endpoint is utilized. Operations that are not updated may continue to use the old URL even after a resource has been modified.

   The next screen that you see will have the specified path and selected HTTP Method. You can optionally provide a short description for this resource and method.

6. On the Get Method page, complete the following fields:

   In the Request parameter section, you can set parameters that become part of the outgoing request. Parameters specify the variable parts of your resource. Click Add Parameters to add a parameter to the request. Complete the following fields:

   • Name: Type the parameter name, for example, param1.
   • Value: Type a value for the parameter, for example, 23.
   • Parameter Type: Select the parameter's type, for example, CFG_PARAM.

     The Parameter Type determines how the parameter should be used. If you select an AWS authentication type, then you must add a mandatory request parameter in all the Actions you create. The parameter name must be aws.service and the parameter type must be CFG_PARAM. Type the service name in the endpoint URL as the parameter value. For example, if the endpoint URL is https://<instance>.s3.com/, type the parameter value as s3.

     REST services rely on HTTP methods (GET, POST, PUT, DELETE, and PATCH) to make requests to a SaaS provider. Thus the parameters are closely tied to these HTTP methods, as they are sent as part of these HTTP method requests. The parameters are part of the HTTP URI.

     CFG_PARAM is an internal configuration parameter.

     URI_CONTEXT parameters are passed as the path component of a REST Resource URI, and the parameter names correspond to the URI path variable names specified in the {} annotation. For example, if the URI is https://api.twitter.com/1.1/users/{id}, the Resource path will be /users/{id}, the parameter type will be uriContext, the parameter name will be id, and the value could be the user id, for example, either 1, or 2, or 3.

     QUERYSTRING_PARAM parameters are passed as the query component of a REST resource invocation request. For example, if the URI is https://api.twitter.com/1.1/users/show.json?screen_name=twitterdev, the resource path will be /users/show.json, screen_name is the name of the parameter, twitterdev is the value of the parameter, and the parameter type is query.

     FORM_ENCODED_PARAM - Define a parameter of type FORM_ENCODED_PARAM, if you want to send the parameter as part of the Request body. FORM_ENCODED_PARAM allows you to send simple key value parameters embedded in the Request body for POST or PUT requests. This uses the default web form encoding, which is application/x-www-form-urlencoded.
     Note: For passing parameters of FORM_ENCODED_PARAM type, you will not be able to define the Request body for a Resource, as the generated parameter key value string will be automatically embedded in the Request body.
   • Mandatory: Select this option if you want this parameter to be made mandatory while creating a flow service. In the request Headers section, allow the client and the server to pass additional information with the request or the response.
     Note: Do not add an authorization header if you use credentials as the mode of authentication.

7. Click Add Header to add a request HTTP header. In the Add Header panel, complete the following fields:

   • Name: Type the Header name.
   • Value: Type a value for the Header.
   • Mandatory: Select this option if you want this Header to be made mandatory while creating a flow service. In the Body panel, complete the following fields:
   • Content Type: If the documentation of the SaaS provider specifies that the content type of the request body is JSON, select application/json as the content type. If the documentation of the SaaS provider specifies that the content type of the request body is XML, select application/xml as the content type. If the documentation of the SaaS provider specifies that the content type of the request body is binary, select Binary as the content type. These options allow you to control the content in an HTTP request body.
   • Document Type: Select a document type for the request body. If you do not have one, you can create a new document type. Click "+" and the Add new Document type page appears.
     • Provide a name and description of your document type.
     • Click Load XML to generate a document type from the XML structure or click Load JSON to generate a document type from the JSON structure.
     • Provide the Name and Type of the field in order to define the structure and content of the document type. A field can be a String, Document, Document Reference, Object, Boolean, Double, Float, Integer, Long, or Short. If you select Document Reference, select the Document Reference. Fields are used to declare the expected content and structure of signatures, document contents, and pipeline contents. In addition to specifying the name and type of a field, and whether the type is an Array, you can set properties that specify an XML Namespace.
     • Indicate whether the field is required at runtime by selecting the Required option.
     • Select the Content Type you can apply to String, String list, or String table variables.
     • After you have entered the details and constraints for each field, click Save.
   Note: Document Types created for a REST connector appears in the Document Types drop-down list for the selected REST connector.

   If the request payload is an array of object, then first create a document type resembling the content of the object, and then select the Array option.

8. Click Next. You will be redirected to the GET Response page.

   You can optionally add more response statuses by clicking the Add Header option. In the Response Body panel, it is mandatory to have one action defined. Click Add body to add one.

   In the Response Body panel, complete the following fields:

   • HTTP Code: Type a single HTTP status code or a code range to indicate the status of the response. Valid values are 100, 101, 102...599 or a range from 100-599.
   • Content Type: If the documentation of the SaaS provider specifies that the content type of the response body is JSON, select application/json as the content type. If the documentation of the SaaS provider specifies that the content type of the response body is XML, select application/xml as the content type. If the documentation of the SaaS provider specifies that the content type of the response body is binary, select Binary as the content type. These options allow you to control the content in an HTTP response body.
   • Error Response: Select this option to handle HTTP errors. If this option is selected when creating a resource, then during the execution of an operation in a Workflow or Flow, if you receive a corresponding Status Code as response from the back end, then an exception will be thrown. For example, let us say, a resource is created with status HTTPs code as 300-500 identified as error response. Then during execution, if we receive any response from 300-500, the operation execution will be considered as failure.
   • Document Type: Select a Document Type for the request body . If you do not have one, you can create a new document type. Click "+" and the Add new Document type page appears.
   • Array: If the response payload is an array of object, then first create a document type resembling the content of the object, and then select the Array option.

9. Click Next. The Add Resource page with all configured details appears.

10. Click Save to create the REST connector.

    The new REST connector (ExternalRESTapi) appears in the REST Connectors page.

1. Go to the REST Connectors page and click New Account.

   The Add Account configuration window appears.

2. Add an account for the REST connector by filling out the required fields.

   Note: If you have added custom fields using the OAuth 2.0 (JWT Client Assertion Flow) authentication method, they will be visible in the Add Account configuration window.

3. Provide an Account Name. All fields will be populated with values. You can add or modify the values if required.

4. Provide a Server URL. This is the login endpoint URL you have specified in the Define Connector page while creating the REST connector.

5. Provide a Consumer ID. Consumer ID is also referred to as the Client ID in OAuth 2.0. This is a client identifier issued to the client to identify itself to the authorization server. For OAuth 2.0, it is the Consumer Key issued by the service provider and used by the consumer to identify itself to the service provider.

6. Provide an Access Token. Access Token is used for authentication and is issued by the authorization server. For OAuth 2.0, it is a value used by the access token consumer to gain access to the protected resources on behalf of the User, instead of using the User's Service Provider credentials.

7. Provide a Session Timeout value. Session timeout value is the maximum number of minutes a session can remain active, in other words, how long you want the server to wait before session timeout (min) terminating a session. The value should be equal to the session timeout value specified at the SaaS provider back end.

8. Provide a Response Timeout value. The number of milliseconds IBM webMethods Integration waits for a response before cancelling its attempt to connect to the back end. In case the response timeout network is slow, or the back-end processing takes longer than usual, increase the response timeout value. It is recommended to specify a value other than 0. If you specify 0, IBM webMethods Integration will wait indefinitely for a response.

9. Provide Retry Count on Response Failure. The number of times IBM webMethods Integration attempts to connect to the back end to read a response if the initial attempt fails. If an I/O error occurs, it will retry only if you have selected the Retry on Response Failure option.

10. Select Retry on Response Failure. Select whether IBM webMethods Integration should attempt to resend the request when the response has failed, even though the request was sent successfully. If so, select true to re-establish the connection.

11. Select Trust store Alias. Select the alias name of the IBM webMethods Integration trust store configuration. The trust store contains trusted certificates used to determine trust for the remote server peer certificates. You can also add a new truststore certificate from this field by clicking the "+" icon.

12. Select Keystore Alias. Select the alias for the IBM webMethods Integration key store configuration. This is a text identifier for the keystore alias. A keystore file contains the credentials (private key/signed certificate) that a client needs for authentication. You can also add a new keystore certificate from this field by clicking the "+" icon. This option is available only if "Credentials" is selected as the authentication type while creating the connector.

13. Select Client Key Alias. This is the alias to the private key in the keystore file specified in the Keystore Alias field. The outbound connections use this key to send client credentials to a remote server. To send the client’s identity to a remote server, you must specify values in both the Keystore Alias and the Client Keystore Alias fields. This option is available only if "Credentials" is selected as the authentication type while creating the connector.

14. Provide Keep Alive Interval. To handle stale connections, set the Keep Alive Interval in minutes.

15. Provide Idle Timeout. The idle timeout interval in milliseconds defines the interval for which a connection will be kept alive if it's idle Timeout not in use. A value 0 keeps the connection alive for the specified value. The default value of -1 implies that the connection will be kept alive until a request fails due to a connection error.

16. Select a value for Enable SNI. Server Name Indication (SNI) is an extension to the TLS protocol by which a client indicates which host name it is attempting to connect to at the start of the handshaking process. Enable this option if the SaaS provider offers SNI-based TLS connectivity, and if you want to connect to an SNI enabled SAAS provider to send the host name specified in the Server URL field, as part of the TLS SNI Extension server_name parameter.

17. Provide SNI Server Name. If you want to explicitly specify a host name to be included as a part of the SNI extension server_name parameter, in case the host name is other than the host name specified in the Server URL field, specify the host name value in the SNI Server Name field.

18. Provide Consumer Secret. Also referred to as the Client Secret, this is a secret matching to the client identifier. For OAuth v2.0, it is the secret used by the Consumer to establish ownership of the Consumer Key.

19. Provide Instance URL. This is an optional field and is used to specify a runtime host, if applicable. This may be required in some back ends like Salesforce.

20. Select Refresh Access Token. Issued with the OAuth v2.0 access token only. A token used by the client to obtain a new access token without having to involve the resource owner.

21. Provide Refresh Token. A token used by the client to obtain a new access token without involving the resource owner.

22. Provide a Refresh URL. This is the provider specific URL to refresh an Access Token.

23. Select Refresh URL Request. This field is available only if authentication type OAuth v2.0 is selected. OAuth 2.0 access tokens typically have a very short lifetime, so when an access token expires, the OAuth profile does not automatically refresh the expired access token. Select the Body Query String and URL Query String options if you want an expired access token to be refreshed automatically. Use the Refresh Token Callback Service option if the back end requires some refresh requests in a custom format, for example, requests which need more parameters than the ones specified by OAuth v2.0, or the back end uses some custom way of organizing parameters, or expects some other HTTP method request (other than POST). If you select this option, you must specify the Flow service name in the Refresh Token Callback Service field.

24. Provide the Refresh Token Callback Service. This is required when the Refresh URL Request is specified as Refresh Token Callback Service. Use this option to specify a new Flow service that the back end requires when adding an account. Click the "+" icon to add the new Flow service to your account. Once you add a Flow service to your account, a framework of the new Flow service is created. You can view the link of the same Flow service on the REST Connectors page.

    Click the Flow Service_Name link in the REST Connectors page to add any implementation for the Flow service. You will then be redirected to the Flow services page for the implementation.

25. Select Enable Connection Pooling. Select this option if you want to enable connection pooling for a connection. When you enable connection pooling, IBM webMethods Integration creates the number of connection instances you specified in the connection's Minimum Pool Size field. Whenever an Integration needs a connection, IBM webMethods Integration provides a connection from the pool. If no connections are available in the pool, and the maximum pool size has not been reached, IBM webMethods Integration creates one or more new connections (according to the number specified in the Pool Increment Size field) and adds them to the connection pool. If the pool is full (as specified in the Maximum Pool Size field), the requesting service will wait for IBM webMethods Integration to obtain a connection till one sec, until a connection becomes available. Periodically, IBM webMethods Integration inspects the pool and removes inactive connections that have exceeded the expiration period of one sec.

26. Provide Minimum Pool Size. The minimum number of connection objects that remain in the connection pool at all times, if connection pooling is minimum pool size enabled. When the connector creates the pool, it creates this number of connections.

27. Provide Maximum Pool Size. The maximum number of connection objects that can exist in the connection pool if connection pooling is enabled. When the connection pool has reached its maximum number of connections, the connector will reuse any inactive connections in the pool, or, if all connections are active, it will wait for a connection to become available.

28. Provide Pool Increment Size. The number of connections by which the pool will be incremented, up to the maximum pool size, if connection pooling is enabled and connections are needed.

29. Provide Block Timeout (msec). The number of milliseconds that IBM webMethods Integration will wait to obtain a connection with the SAAS provider before the connection times out and returns an error. For example, you have a pool with maximum pool size of 20. If you receive 30 simultaneous requests for a connection, 10 requests will be waiting for a connection from the pool. If you set the Block Timeout to 5000, the 10 requests will wait for a connection for 5 seconds before they time out and return an error. If the services using the connections require 10 seconds to complete and return connections to the pool, the pending requests will fail and return an error message stating that no connections are available. If you set the Block Timeout value too high, you may encounter problems during error conditions. If a request contains errors that delay the response, other requests will not be sent. This setting should be tuned in conjunction with the maximum pool size to accommodate such bursts in processing. The default value is 1000 msec

30. Provide Expire Timeout (msec). The number of milliseconds that an inactive connection can remain in the pool before it is closed and removed from the pool, if connection pooling is enabled. The connection pool will remove inactive connections until the number of connections in the pool is equal to the Initial Pool Size. The inactivity timer for a connection is reset, when the connection is used by the connector. This setting should be tuned in conjunction with the initial pool size to avoid excessive opening and closing of connections during normal processing. The general recommendation is to keep the Expire Timeout value equal to the Session Timeout value. The default value is 1000 msec

31. Select a Session Management value. The access token is refreshed whenever the session expires. Session expiration is handled according to the setting of the Session Management property in your configuration. To refresh the 'Access Token' automatically, set the Session Management to either fixed or auto. The Timeout value should be based on the back-end settings.

    If Session Management is set to none, then access token will not be refreshed.

32. Click Add. With this, you have successfully configured the REST connector account. Click the drop-down arrow beside the connector to view the account configured for the connector.

    Note: The accounts created for REST connectors using the Flow Editor do not display the Edit and Delete icons when the same Accounts are displayed on the Connectors page in IBM webMethods Integration. You can use the existing accounts configured using the Flow Editor, but you cannot edit or modify the account details. Ensure that you create a new account for the REST connectors if any changes are required for the existing accounts. Further, the accounts created for REST connectors using the Flow Editor cannot be used in Workflows, that is, pre-existing accounts will not be available in the Connect to drop-down list while creating a Workflow. Ensure that you create new accounts in such cases.

    Once you have configured the account for the REST connector, the next step is to configure an operation for the connector.

1. Go to the REST Connectors page and click Operations. The Custom Operations page appears.

2. On the Custom Operations page, click New Operation. The Show i/o signature and Test operation options are available on the Custom Operations screen and appears for all custom connector operations. The Show i/o signature option allows you to only view the Input and Output signature of the custom operation. The input and output fields cannot be edited. You can click the input and output fields to view the field properties. The Test operation option allows you to test the custom operation. Specify the Account name and the Input data and then click Run to test the operation and view the test results in the Result window. For array inputs, you can add the array items and then add the values. If an operation does not have an input signature, the input fields are not displayed.

   On the Connect to account page, select an account that you configured for the connector. Each connector uses an account to connect to the provider's back end and perform operations. You can also create new account by clicking the "+" icon.

3. Provide a name and description of the custom operation.

4. Click Next.

5. Select the operation.

6. Confirm the operation and click Done.

With this you have created a REST connector, configured an account and operation. The connector is now ready for the execution of services.

OAuth 2.0 (JWT Client Assertion Flow) is an authentication method used for connecting to REST endpoints in a secure way. This method enables you to generate access tokens for backends that utilize OAuth 2.0 by allowing clients to create digitally signed JWT assertions.

Adding custom fields

With the OAuth 2.0 (JWT Client Assertion Flow) authentication method, you can include custom fields in the Add Account window when setting up an account for a REST connector.

1. When you select the OAuth 2.0 (JWT Client Assertion Flow) method from the Authentication Type drop-down list, the Add Field button appears on the screen. Click on this button to configure the REST connector using this authentication method.

   The Add button configuration window appears on the screen. This window allows you to define custom fields that are displayed in the Add Account configuration window when setting up an account for the REST connector.

2. Fill in values for the required fields as per the following instructions:

   • Select Field Category: Choose a field category from the following options: Header, Claim, JWT Client Assertion

     • Header - Header is typically the first part of the token. It serves as a container for metadata that provides information about how the token is secured and should be processed.

       Note:

       Currently, IBM webMethods Integration supports this authentication method for Microsoft endpoints only. So, to ensure the successful creation of a REST connector, it is essential to include an ‘x5t’ header value. x5t is a base64-encoded SHA-1 thumbprint associated with the X.509 certificate. When you enter ‘x5t’ as the header value in the ‘Name’ field, a custom field appears in the ‘Add Account’ configuration window with a ‘+’ button. You can use this button to select an X.509 certificate from your local folder. After uploading the X.509 certificate, IBM webMethods Integration automatically calculates the ‘x5t’ value, which is then displayed in the field.

     • Claim - Claim is an essential part in JWTs, providing context and additional information about the token. Currently, IBM webMethods Integration supports this authentication method for Microsoft endpoints only. So, to ensure the successful creation of a REST connector, it is essential to include an ‘exp’ claim value. exp or expiration time is the time (in minutes) after which the JWT expires.
     • JWT Client Assertion - A JWT client assertion is a specific type of JWT used in OAuth 2.0 authentication. It serves as a means for a client (an application or service) to prove its identity when requesting access to protected resources from an authorization server.Currently, IBM webMethods Integration supports this authentication method for Microsoft endpoints only. So, to ensure the successful creation of a REST connector, it is essential to include ‘client_id’ and ‘scope’ assertion values. client_id is an unique identifier associated with the application while scope is the resource identifier (application ID URI) of the resource you want, affixed with the .default suffix. For example, https://graph.microsoft.com/.default.

   • Name: Specify the name for the selected field category.

     The value for this field is case-sensitive. For example, for Microsoft endpoints, it is mandatory to include ‘X5T,’ ‘expiration time,’ ‘client ID,’ and ‘scope.’ The names for these values should be ‘x5t,’ ‘exp,’ ‘client_id,’ and ‘scope,’ respectively.

   • Display Name: Provide a suitable display name for this field. For example, Client ID.

   • Description: Provide a short summary for this field.

   • Select Data Type: Select the data type you want to assign to the value of this field. Available values are String, Integer, anyURI, Boolean.

   • Default Value: Specify the default value you want to set for this field.

   • Allowed Values: Define the values you want to set for this field.

   • Field Properties: Enable the specific property you want to set for this field. Available properties include Array, Required, Encrypted, Hidden.

3. Once you have filled in all the required details, click Add. This action successfully creates and adds the custom field to the list of custom fields in the Define Connector screen. The created custom field then appears on the Add Account configuration window when you are setting up an account for a REST connector.

In the earlier section, we created a REST connector and configured the REST connector account. Now let us understand how to invoke a REST API in a Flow service using a REST connector.

1. From the IBM webMethods Integration navigation bar, click Projects. Select a project and then select Flow services. Click the "+" icon to start creating a new Flow service.

2. Provide a name and description of the new Flow service. For example, ExternalRESTAPIFlow

3. On the Flow service, click CONNECTORS.

4. Type ExternalRESTapi in the search box, select the connector, and then select Add Custom Operation.

5. On the Connect to account page, select the connection name and provide a name and description of the connection.

6. Click Next and select the getgetEmployeeList operation.

7. Confirm the action to create the custom operation.

8. On the Flow service editor, you will see that the account is now configured.

9. Click the "Map" icon to view the Flow service mapping.

10. Save the Flow service and click Run. As the results show, the employee details are fetched.

The Dynamic Account feature enables you to dynamically override certain details of the account you are using to run a custom action created under a custom REST connector.