Using the REST Adapter

Representational state transfer (REST) or RESTful web services are a way of providing interoperability between computer systems on the Internet. REST-compliant web services allow requesting systems to access and manipulate textual representations of web resources using a uniform and predefined set of stateless operations. Other forms of web services exist which expose their own arbitrary sets of operations such as WSDL and SOAP.

"Web resources" were first defined on the World Wide Web as documents or files identified by their URLs, but today they have a much more generic and abstract definition encompassing every thing or entity that can be identified, named, addressed, or handled, in any way whatsoever, on the web. In a RESTful web service, requests made to a resource's URL will elicit a response that may be in XML, HTML, JSON, or some other defined format. The response may confirm that some alteration has been made to the stored resource, and it may provide hypertext links to other related resources or collections of resources. Using HTTP, as is most common, the kind of operations available include those predefined by the CRUD HTTP methods GET, POST, PUT, DELETE, and so on.

By using a stateless protocol and standard operations, REST systems aim for fast performance, reliability, and the ability to grow, by re-using components that can be managed and updated without affecting the system as a whole, even while it is running.

Architectural Constraints are:

• Client-server architecture

• Statelessness

• Cacheability

• Layered system

• Uniform interface

• Resource identification in requests

• Resource manipulation through representations

• Self-descriptive messages

The figure illustrates, how the RESTFUL adapter works.

A client sends a message about the HTTP application protocol to a REST API interface.

The presentation format can be JSON, XML, RSS/ATMO feed or any other format.

The API layer that implements the HTTP application protocol has distributed the request to the application layer that resolves the URL to a specific resource.

The resource is delivered by the data layer with the concrete data.

One of the requirements for a REST interface was a universal interface for all clients. This is achieved by using HTTP methods or verbs. The functionality of the app implementation is determined by these verbs. For example, an update is determined with PUT or POST.

REST Adapter – Overview

The figure illustrates an overview about REST adapters.

The following are further details about the directions:

From REST to XI and Back

What the REST Adapter mainly does is to allow mapping information between HTTP calls and XI messages.

For HTTP calls, the adapter can access information from the URL and the URL parameters, from the HTTP operation (GET, POST, PUT, DELETE), from the HTTP Header (for example, cookie or encoding information) and the payload itself. On XI Messages the adapter can access information from the XI message header and payload.

From HTTP Call to XI Message

When converting a HTTP call into a XI Message, selected information, except the payload, are taken from the HTTP call and written into XI Header variables.

For convenience, the REST adapter defines a predefined set of XI Header variables like (URL, service, resource, ID, operation, and so on) that can be filled with information from a HTTP call for later use in the Integration Flow or diagnostic purposes.

The payload can be taken as it is, converted into UTF-8 code page and can be converted from JSON into XML and the other way around.

For XI Messages that expect XML and are bound to an interface or operation, the adapter can enclose the payload XML with a given or calculated interface or operation name, based on the incoming HTTP call information.

From XI Message to HTTP Call

On receiver side, the REST Adapter generates dynamically an HTTP URL from information provided in the configuration and from XI Header and XI Payload. Based on given rules, the interface or operation name can be used to determine the HTTP operation to use (POST, PUT, GET and DELETE). The payload can be converted to format (XML, JSON) and a code page that the REST service is expecting.

Let’s have a look what is happening behind the scenes.

Using the REST Adapter, you can create an Integration Flow with a REST API on sender side. The adapter would then convert incoming HTTP calls into XI messages and the other way around (for synchronous scenarios).

The REST Adapter allows dynamic dispatching of an incoming HTTP call to a sender channel by using the URL, the HTTP operation, or parts of the content as selection criteria.

In general REST Adapter is processing requests under the following URL root:

http:<myHost:<myPort/RESTAdapter/

In most cases, you will want to bind the fixed part of your REST URL to a specific PI channel. You have to set up the channel endpoint name, so that it looks like the following:

http:<myHost:<myPort/RESTAdapter/API/V2.0/Customer

If you want to serve just a single REST API, the dynamic part is rather static like the following:

http:<myHost:<myPort/RESTAdapter/API/V2.0/Customer_Create

If you want more than one REST URL to be bound to a single channel, you can use URL patterns like the following:

…/RESTAdapter/API/V2.0/{resource}/{id}?operation={opname}

This URL pattern would serve the following:

…/RESTAdapter/API/V2.0/customer/123?operation=create

as well as the following:

…/RESTAdapter/API/V2.0/order/222?operation=delete

But it would not match the following:

…/RESTAdapter/API/V2.0/order?operation=create

Because the {id} part is missing in the URL.

The fixed endpoint name does not have to be unique between PI channels. For channel selection the adapter also uses the dynamic part of the URL as well as a simple filter based on the payload content. You can limit the channel only to process incoming messages with a specific value in a JSON object or XML tag.

Having this dynamic channel selection feature, you can hide complex message processing landscapes behind a few APIs.

You can also use the HTTP operation (get, put, post, delete) as a selection criteria for a channel. That allows you for example to set up two Integration Flows with the same URL, but one used for insert operations (POST) and the other used for updates (PUT).

Result of this step is that the Adapter found a matching channel for further processing of the message. If no channel was found, a HTTP error will be returned.

REST services usually use JSON as payload format, while PI used to work on XML documents, therefore, the adapter allows converting an incoming JSON payload into XML. For synchronous calls the result message can also be converted on its way back.

It is also possible here to specify the charset of the payload.

Because the adapter allows using data of the payload for dynamic configuration, the payload conversion is done at an early stage.

In this step, the information of the various parts of the incoming HTTP are processed and stored in custom or predefined variables. The placeholders in the URL pattern allow the specifying of dynamic parts of the URL. In addition, the adapter allows in this step to map information from the HTTP call to predefined or custom variables for later use in the integration flow. These variables are stored in the XI message header.

A REST call has a predefined operation semantic that is usually bound to the HTTP operation, such as the following:

• GET for fetching data.

• POST for creating an object.

• PUT for updating an object.

• DELETE for deleting an object.

For example a HTTP DELETE on http://myhost:myport/customer/99 is a common URL pattern that in this case allows the deletion of the object customer with id 99. But the logical REST operation can also be encoded in the URL or an URL parameter and does override the HTTP operation, so the REST operation is part of the URL. Such a REST API could look like the following:

HTTP POST on http://myhost:myport/customer/99?operation=remove

In this step, the REST adapter sets the logical REST operation, based on the user configuration. After this step, we have mapped all necessary information from the incoming call to the new XI message.

XI channels are usually bound to an interface or operation and XI expects in such cases that the payload is in XML format and that the outermost element contains the interface or operation name.

Assume that the incoming payload is not PI aware and is in JSON format. The adapter would then convert the JSON to XML and in this step add the missing interface or operation name.

Because the channel allows processing of multiple REST URLs, the user has to configure rules for adding the correct outer XML element, based on the information of the incoming call. The rules can make use of the predefined or custom variables and do allow a simple pattern matching type, called Glob.

If you want to match a group of values and not only an exact value, you use a Glob expression. The rest adapter supports two wildcard characters.

In this final step, the message is sent from the REST Adapter to the PI message system.

For synchronous calls with result message, the returning XI message is converted back into the desired format and code page and returned as the result of the incoming HTTP call with a HTTP status of 200.

Custom Error Handling is an optional feature that allows to ignore or to create error conditions.

On sender side this feature can be triggered by any error (Exception) within the adapter, like JSON/XML conversion error, configuration error, and so on.

In addition the feature can be triggered by the content of a result message in synchronous call scenarios (JSON object value, XML element value, Text). When checking the value, text Globs can be used.

The behavior of the feature after being triggered can be customized by the chosen strategy. This can be one of the following:

• Error – Log an error and treat message delivery as NOT successful.

• Ignore Error – Log the error and treat message delivery as successful.

• Custom Result – Set the message delivery as successful and returns a custom HTTP status code and message payload.

Using the REST Adapter, you can call other REST services as part of your Integration Flow. The adapter converts outgoing XI messages into HTTP calls and in synchronous scenarios, sends back the HTTP result as XI message.

In the first step, the outgoing message is taken from the PI messaging system and payload as well as the dynamic header variables is extracted for further processing.

Using the REST Adapter you can call other REST services as part of you Integration Flow. The adapter converts outgoing XI messages into HTTP calls and in synchronous scenarios sends back the HTTP result as XI message.

In the first step, the outgoing message is taken from the PI messaging system and payload as well as the dynamic header variables is extracted for further processing.

If the incoming payload is XML, the adapter extracts the interface or operation name from the outermost XML element. You can add own rules defining how to map the interface or operation along with its namespace name to dynamic variables.

The URL to be called can either be a static URL or a dynamically generated URL by using placeholder variable values that have been set up during the previous steps.

For dynamically generated URLs, you have to specify the dynamic parts of the URL with placeholder variables in curly brackets (similar to sender channel configuration), so that it looks like the following:

http://www.google.com/finance/info?q={stock_symbol}.

The custom placeholder variable "stock symbol" has now to be bound to the source where the value is coming from.

Types of sources are as follows:

• Manual Value: Just provide a manual value yourself.
• Adapter Specific Attribute: Refer to an XI Header variable.
• XPath: Reference an XML element from the incoming XML payload.
• JSON Expression: Reference a JSON object.
• Binding: Specify a value from the channel interface binding.

For each incoming message, a new URL will be generated.

Similar to the previous step, the HTTP operation to be used for the HTTP call can be either static and manually set up or can be calculated based on the incoming XI message.

If the HTTP operation has to be determined dynamically, you specify the source of the value to be used as selection criteria and provide a matching value or GLOB expression for each of the four HTTP operations. The source types are the same is in previous step when generating the URL.

For rare cases when you need more than one rule per HTTP operation, the UI provides a table where you can add more rules.

If the REST service requires certain HTTP Header values, these can be set up as manual values or can reference dynamic variables set up in the previous steps.

In case the XI message is in XML format and does contain the interface/operation as the outermost element and this element is not expected by the REST service you are calling, you can set up the adapter to strip it off.

If the payload from the XI message system does not match the target format you can again add code page and format conversion is this step.

Last step is then to call the remote REST service. Depending on the returned HTTP status code, the processing is then successful or not.

Optional: Result message processing and Response Determination

In case of a synchronous scenario, the result message returned from the HTTP server will be sent back to the PI messaging system.

This step also contains optional code page and format conversions.

If the channel is bound to an interface or operation, the result has to be in XML format and has to contain the response interface or operation as the outermost element. This is done automatically by the adapter. You just have to specify rules in order to determine which interface or operation to be used.

The configuration is similar to the operation rules, but instead of setting variable and value, you can set response interface or operation and namespace.

Similar to the sender channel, the receiver allows setting up custom handling of error conditions.

This feature can be triggered by any kind of error in the receiver adapter (errors during conversion, configuration, invalid URL, and so on) or based on the HTTP result (status code, status text, payload content).

If a rule that you specify on this information is triggered, you can force an error condition, you can ignore the error or create a custom result message that, if in synchronous scenario, then will be sent back to the PI messaging system.

This feature is necessary especially on REST receiver channels. Imagine you want to call a remote server in order to delete a customer with a certain ID and the URL is dynamically created by the adapter. The remote REST URL could look like the following:

http://server:port/API/Customer/222?op=delete

If the HTTP server returns a HTTP code of 404 (not found), the adapter cannot decide whether the URL is incorrect or whether the customer with ID 222 just does not exist. The semantic of the HTTP result is dependent on the implementation of the specific REST API and so it needs to be configurable.

In addition to the basic applications (Consuming synchronous RESTful service and exposing a function module as RESTful service), there are others that are of interest. These are briefly described below:

• JSON toXML conversion.

• Defining a dynamic endpoint.

• Using dynamic attributes.

• Same endpoint for multiple Integration Flows.

• PI REST Adapter – Custom error handling.

• PI REST Adapter – Define custom http header elements.

There is a series of blogs that deal in detail with these topics. These blogs can be found at https://blogs.sap.com/2014/12/18/pi-rest-adapter-blog-overview/