Creating a custom REST connector manually

Learn how to create a custom REST connector manually.

1. Click Projects.
2. Select a project and then click Connectors > REST > Add Connector.
3. In the Define Connector page, complete the details of the fields as mentioned here:
   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 that you enter here appears on the Connectors page.
   • Authentication Type: Every backend provides its own authentication mechanism. Get the authentication details from the backend documentation and select the supported authentication type from the drop-down list. REST connector supports the authentication types as follows:
     • 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, webMethods Integration supports the OAuth V2.0 (JWT Client Assertion Flow) authentication method exclusively for Microsoft endpoints.
       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 based on a 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, make sure 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 details of the fields as mentioned here:

   • 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 that is 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, user ID, 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 that the new endpoint is used. Operations that are not updated might 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 fields as mentioned here:

   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 fields as mentioned here:

   • 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 is /users/{id}, the parameter type is uriContext, the parameter name is ID, and the value might be the user ID.

     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 is /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, when you want to send the parameter as part of the Request body. FORM_ENCODED_PARAM allows you to send simple key value parameters that are 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: When passing parameters of the FORM_ENCODED_PARAM type, you cannot 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 when 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 window, complete the fields as mentioned here:
   • 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 window, complete the fields as mentioned here:
   • Content Type: If the SaaS provider's documentation specifies that the Request Body Content type is JSON, selectapplication/json. If it specifies XML, select application/xml. If it specifies binary, select Binary. These options let you control the content type of the 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 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 run time 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 that are created for a REST connector appear in the Document Types list for the selected REST connector.

   If the request payload is an array of objects, first create a document type that matches the object's content, then select the Array option.

8. Click Next. You are redirected to the GET Response page.

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

   In the Response Body window, complete the fields as mentioned here:

   • 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 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, an exception is produced during the execution of an operation in a workflow or flow service if the backend returns the corresponding status code. For example, if a resource is created with HTTP status codes 300–500 identified as error responses, any response within this range during execution is considered a 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 that matches 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.