Invoking a REST service

Discover a REST service from a local OpenAPI specification (formerly known as Swagger) and generate 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.

For example, you can use an external service to invoke the following services:

Watson services: For more information about Watson APIs, see Watson API Explorer.
IBM® Operational Decision Manager business rules: For more information about using business rules, see Using IBM ODM business rules.
Hyperledger Composer services:
- For more information about using Hyperledger Composer, see Build Blockchain applications and business networks your way.
- For a developerWorks tutorial that explains how to integrate an external blockchain service in a business process, see Combine business process management and blockchain.

Before you begin

You must have a file with a valid OpenAPI specification that is locally available on your computer. 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.

About this task

To use a REST service in Process Designer, you discover the service and select the operations that you want to use. Then, set the server that contains the configuration properties that are required to invoke the service. An external service is generated containing the operations that you selected in the discovered service and a reference to the server that you selected. Business objects are also generated based on the OpenAPI specification.

Service providers update their services periodically, and you might want to rediscover the updated service so that you can use it. When you discover a service, if an external service discovered from the same file already exists in Process Designer, you can either overwrite the existing service or create a new one. To get the updated version of the REST service, replace the external service. 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.

Procedure

To discover an existing REST service with an OpenAPI specification and generate an external service that you can use in a service flow, complete the following steps.

Create an external service in one of the following ways:
- Beside Services in the library navigation, click the plus sign (+). Select External Service. In the New External Service page, choose Java, REST or Web service.
- In the Service Flow editor, select a Service task. In the Implementation tab for the service, click New.
Select Browse local files (Swagger) and browse to the file. Click Next.
You might see one or both of the following:
- A list of operations that are not supported by the tool. These operations will not be included in the generated external service and are therefore not available to be invoked in a service task. You can click View Error to see the reason why the operation is not supported. To invoke these operations, you must use JavaScript API. To make these operations available for invocation by using JavaScript, you must complete the service discovery and generate an external service. You can view the operations in the source view of the External Service editor. See Invoking a REST service by using JavaScript.
- A list of operations that have warnings in the OpenAPI specification. You can view the warnings for each operation. The generated external service will include a corresponding operation, but you might get unexpected results when you run the service. After viewing the warning, if you do not want to include the operation, you can remove it in the next step.
Click Next.
The discovered operations are listed. Select the operations that you want to include in the external service, and click Next.
If the OpenAPI specification was already discovered, you can create a new service or replace the existing one. Click Next.
Set the server that contains the properties used to invoke the REST service. Either select an existing server, or create a new one based on information in the OpenAPI specification. Click Finish.

Results

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.

In the Details section, the service name and its documentation is shown.
Selecting Binding shows the binding type of REST and the server. If your server binding properties change, you can select a different server.
Selecting Source shows the OpenAPI specification source in read-only mode. This is useful for viewing the operations that you want to invoke using JavaScript API.
In the Data library section, you might see business objects as a result of generating the REST API service. These business objects are only for the external service and are read-only. Deleting the external service also deletes these business objects.

After your service is created, you can select it as an implementation of a service task in a service flow. Select the operation that you want to use from the operation list and map the inputs and outputs in the Data Mapping tab. If you are using JavaScript to invoke your operation, enter your JavaScript in a script task in a service flow. See Creating a service flow and Invoking a REST service by using JavaScript.

To catch any errors that might occur in the service, attach a catch all boundary error event to it, as described in Catching errors by using error boundary events.