REST APIs

In IBM® App Connect Enterprise, a REST API is a specialized application that can be used to expose integrations as a RESTful web service that can be called by HTTP clients. IBM App Connect Enterprise also provides a set of REST nodes, which you can use to interact either synchronously or asynchronously with external REST APIs.

A REST API describes a set of resources, and a set of operations that can be called on those resources. The operations in a REST API can be called from any HTTP client, including client-side JavaScript code that is running in a web browser. You can also use the IBM App Connect Enterprise REST nodes to call and interact with external REST APIs. For information about using these REST nodes, see Connecting to external REST APIs.

The REST API has a base path, which is similar to a context root. All resources in a REST API are defined relative to its base path. The base path can be used to provide isolation between different REST APIs, as well as isolation between different versions of the same REST API. For example, a REST API can be built to expose a customer database over HTTP. The base path for the first version of that REST API could be /customerdb/v1, while the base path for the second version of that REST API could be /customerdb/v2.

The REST API describes a set of resources. The HTTP client uses a path relative to the base path that identifies the resource in the REST API that the client is accessing. The paths to a resource can be hierarchical, and a well designed path structure can help a consumer of a REST API understand the resources available within that REST API. The following table lists some example resources for a customer database in the REST API:

Table 1. Example resources
Resource	Description
/customers	All the customers in the database
/customers/12345	Customer #12345
/customers/12345/orders	All orders for customer #12345
/customers/12345/orders/67890	Order #67890 for customer #12345

Each resource in the REST API has a set of operations that can be called by an HTTP client. An operation in a REST API has a name and an HTTP method (such as GET, POST, or DELETE). The name of the operation must be unique across all the resources in that REST API. Additionally, a single resource can have only one operation that is defined for a specific HTTP method. The combination of the path and the HTTP method that are specified by the HTTP client that is making the request is used to identify the resource and operation that is being called.

The following table lists example operations for the resource /customers/12345:

Table 2. Example operations
HTTP Method	Operation Name	Description
GET	getCustomer	Retrieve the customer details from the database.
PUT	updateCustomer	Update the customer details in the database.
DELETE	deleteCustomer	Delete the customer from the database.

To call the updateCustomer operation, the HTTP client makes an HTTP PUT request to /customerdb/v1/customers/12345

Each operation in a REST API can also have a set of parameters that can be used by the HTTP client to pass arguments into the operation. Each parameter must be defined in the definitions for the REST API. Each parameter has a unique name and type. Several types of parameters are supported by REST APIs in IBM App Connect Enterprise:

Path parameters: Can be used to identify a particular resource. The value of the parameter is passed in to the operation by the HTTP client as a variable part of the URL, and the value of the parameter is extracted from the path for use in the operation. Path parameters are denoted by using the syntax {paramName} in the path to the resource. For example, the customer ID can be passed in as a path parameter named customerId:
/customers/{customerId}
Query parameters: The value of a query parameter is passed in to the operation by the HTTP client as a key value pair in the query string at the end of the URL. As an example, query parameters can be used to pass in a minimum and maximum number of results that should be returned by a particular operation:
/customers?min=5&max=20
Header parameters: The HTTP client can pass header parameters to an operation by adding them as HTTP headers in the HTTP request. As an example, header parameters might be used to pass in a unique identifier that identifies the HTTP client that is calling the operation:
Api-Client-Id: ff6e2c5d-42d5-4026-8f7f-d1e56da7f777

A single operation can define and accept multiple parameters of all three types. Additionally, depending on the HTTP method of the operation, the operation can accept data from the HTTP client in the request body. Operations can also send data back to the HTTP client in the response body. REST APIs in IBM App Connect Enterprise are configured by default to process JSON data, but it is possible to process data in various formats.

Each operation in the REST API must be implemented as a subflow. A subflow for an operation has a single input node, and a single output node. The implementer of the operation can build the subflow for the operation by using all of the standard message flow nodes available with IBM App Connect Enterprise.

When an HTTP client makes a call to an operation in a REST API that is deployed to an integration server, the request is automatically processed and routed to the input node in the corresponding subflow for that operation. When that subflow propagates a message to its output node, the message is automatically routed back to the HTTP client. The author of the REST API is not required to do anything to handle the HTTP transport.

To create a REST API in IBM App Connect Enterprise, you can define the models, resources, and operations from scratch, or you can use the IBM App Connect Enterprise Toolkit to import a Swagger document or an OpenAPI 3.0 document that describes the resources and operations that you want in the REST API. For more information, see Developing integration solutions by using REST APIs and Creating a REST API.

When you have created and deployed a REST API, you can push (export) the REST API definition to IBM API Connect. You can push one or more REST APIs to IBM API Connect by using either the IBM App Connect Enterprise web user interface or the mqsipushapis command. For more information, see Pushing REST APIs to IBM API Connect.