Consuming RESTful CRUD services with Advantco REST adapter

[engswee]

Introduction

With the increase of mobile and cloud solutions, RESTful services are becoming popular as a lightweight HTTP-based alternative for integration between applications.

In this article, I will share my experience of developing interfaces for consuming RESTful services with Advantco's REST adapter. Even though SAP has recently come up with their own REST adapter, some required features like OAuth 2.0 will only be available in future SPs based on SAP's REST adapter product roadmap.

RESTful services key points

Below are some key points when consuming RESTful services.

1) Resource URL

The URL where the service is located, which includes the host and port of the server and the path to the service.

Example: http://host:port/path

2) HTTP method

The HTTP request method that will used in the HTTP call.

Example: GET, POST, PUT, DELETE

3) URL parameters

Additional parameter name & parameter values to be passed to the service as a query string.

Example: http://host:port/path?param1=value1&param2=value2

CRUD services

Certain web services provide CRUD (Create, Read, Update, Delete) functions as a means of allowing external clients to manage data in the server in a database-like manner. Below we will see how consumption of these CRUD functions of the web services can be achieved with the different HTTP methods available in the REST adapter.

1) GET

The HTTP GET method can be used to execute a Read function to retrieve/query data from the server.

Below is a sample receiver channel using the GET method. In the resource URL, we can specify an additional dynamic query string that is used to provide further selection parameter values to the service.

The query string from the above Resource URL will be dynamically retrieved from the payload via variable substitution.

At runtime, the field <queryString> in the target payload is populated dynamically during mapping.

When the REST adapter executes the HTTP GET request, the message log shows that the value of the query string is populated in the resource URL. The OAuth 2.0 authentication token is passed via the Authorization field in the HTTP header.

2) POST

The HTTP POST method can be used to execute a Create function to create new data in the server.

Below is a sample receiver channel using the POST method. There are no additional parameters in the resource URL as the data is passed in the Request Body with the message payload.

At runtime, the target payload that will be used for the data creation is populated.

When the REST adapter executes the HTTP POST request, the message log shows that the payload is included in the request body.

3) PUT

The HTTP PUT method can be used to execute an Update function to modify data in the server.

Below is a sample receiver channel using the PUT method. In the resource URL, we can specify a variable so that the path is a dynamic value. Note that this is different from a query string in the GET example above. The data to be changed is passed in the Resource Body with the message payload.

The variable will be dynamically retrieved from the payload via variable substitution.

At runtime, the target payload that will be used for the data update is populated.

When the REST adapter executes the HTTP PUT request, the message log shows that the URL path is extended with the dynamic value and the payload is included in the request body.

4) DELETE

The HTTP DELETE method can be used to execute a Delete function to delete data in the server.

Below is a sample receiver channel using the DELETE method. In the resource URL, we can specify a variable so that the path is a dynamic value. Also, an additional URL parameter is added to form part of the query string. Note that there is no Resource Body for this request.

The variable and URL parameter will be dynamically retrieved from the payload viavariable substitution.

At runtime, the fields that will be used for variable substitution are populated dynamically during mapping.

When the REST adapter executes the HTTP DELETE request, the message log shows that the URL path is extended with the dynamic value and an additional parameter is added in the query string. Also there is no request body.

Additional points for consideration

During the development, we also need to take into consideration the following additional points that might affect the design of the interface.

Static vs dynamic query string

The query string may be:

Static - having only mandatory parameters

Example: http://host:port/path?mandatoryParam1=value1&mandatoryParam2=value2

Dynamic - having one or more optional parameters

Example: http://host:port/path?mandatoryParam1=value1&optionalParam2=value2&optionalParam3=value3

The URL parameter table of the adapter only supports static query string, as shown in the DELETE example where the parameter will always be added into the Resource URL. For dynamic query string which contains optional parameter depending on the message content, the query string has to be constructed dynamically with mapping as shown in the GET example.

Custom HTTP headers

Custom HTTP headers can be added to the request in the "Enable Custom Request HTTP Headers" section. In the DELETE example, the service requires the content type to be set in the header even though there is no resource body. Therefore an entry is added in the custom header section for Content-Type = application/xml.

Empty response body

For certain services, it might not return any content if the request is successful. Therefore, there is no response body as shown in the PUT and DELETE example. One approach to handle successful empty response is to just map a constant value to the target response message of the original caller.

Fault handling

Application and system errors during the calling of the service can be handled by defining fault messages for the sender and receiver service interfaces and linking them via an fault mapping.

Useful development tools

The following tools have also been very useful during the development and testing of the interfaces.

Advantco REST workbench

Without doubt, this is the single feature that I love most about the Advantco REST adapter. It provides a REST client that allows the developer to test out the configuration of the REST adapter even before creating a channel or iFlow. It is also useful for debugging purposes - testing connectivity, authentication, format conversions, etc. I have not gotten my hands on SAP's own REST adapter, but as SAP's own solution matures, I do hope that there will be a similar feature.

The workbench can be accessed at http(s)://:/webdynpro/dispatcher/advantco.com/rest~workbench/RESTAdapterWorkbench

Chrome Advanced REST client

This free extension for the Chrome browser is also another very useful tool for testing REST services. It is similar to using SoapUI for testing SOAP services.