Calling external REST services

You can use an external service to call a REST service on a system that is external to IBM Business Automation Studio. For example, you can discover a REST service, select the operations that you want, and call the REST service in business applications.

About this task

An external service provides a model artifact that you can use to call a REST service from business applications. An external service defines operations, their inputs and outputs, and a server that contains information about how to connect to the external system. You discover a REST service from an OpenAPI specification (formerly known as Swagger) and call an external service based on the discovered REST service. You can then use the external service in a service flow to invoke the REST service.
Important: You must have a valid and complete OpenAPI 2.0 ( or 3.0) specification that includes the necessary security definitions. The OpenAPI format can be either JSON or YAML. To verify that your OpenAPI specification is valid, open the file in an OpenAPI editor or a Swagger editor.

Procedure

To create and invoke an external service that invokes a REST service, complete the following steps:

  1. Open a business application in the designer.
  2. Ensure you are using the Advanced view mode, set under your user preferences.
  3. In the left navigation menu, select Action and services > External service.
  4. Point to the URL or browse to a file that contains the OpenAPI definition of the external REST service, choose the operations you want included in the external service, and select the server or create a new server connection.
    An external service is created. The operations and their inputs and outputs are based on the operations that you selected in the discovered REST service. The Source view shows the OpenAPI definition of the external REST service in read-only mode.
  5. Specify the authentication credentials in the Binding view used to call the external REST service. An external service must refer to the server that contains the connection information.
  6. Depending on the type of operation, you can invoke a REST service in one of the following ways:
    • By selecting an operation in a service task, mapping the inputs and outputs, and calling the service task in an action. When you discover a REST service, the operations that you select are included in the external service and they are available for invocation by a service task. For more information about adding a service task, see Calling actions.
    • By using JavaScript, which is the case for some REST operations. After the discovery, you see a list of the operations that couldn't be generated and invoked directly by service task. For more information, see JavaScript APIs for actions.

What to do next

Service providers often change or update their REST service. When there is a new, compatible version with additional capabilities you would want to use in your business application, you must rediscover the service. When you rediscover a service that already exists in your business applications, you can choose to replace the existing service or create a new one. If the connection information changes, you don't need to rediscover the service. You can change the properties in Binding view. If you have a service task for the external service, their operations and data mappings are preserved, unless the operation or data is not included in the new version. If the server connection information is unchanged, you can keep the reference to the server information.