In IBM® Integration Bus, 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.
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.
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.
Resource | Description |
---|---|
/customers | All of 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 of 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.
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
/customers/{customerId}
/customers?min=5&max=20
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 Integration Bus 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 Integration Bus.
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 Integration Bus, you must first define the resources and operations that are available in the new REST API. Those definitions must be specified in a Swagger document, an open specification for defining REST APIs, see Swagger.