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.

/wp-content/uploads/2015/01/get1_623063.png

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

/wp-content/uploads/2015/01/get2_623064.png

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

/wp-content/uploads/2015/01/get3_623065.png

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.

/wp-content/uploads/2015/01/get6_623066.png

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.

/wp-content/uploads/2015/01/post1_623067.png

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

/wp-content/uploads/2015/01/post2_623068.png

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

/wp-content/uploads/2015/01/post3_623069.png

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.

/wp-content/uploads/2015/01/put1_623070.png

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

/wp-content/uploads/2015/01/put2_623071.png

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

/wp-content/uploads/2015/01/put3_623072.png

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.

/wp-content/uploads/2015/01/put4_623073.png

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.

/wp-content/uploads/2015/01/del1_623074.png

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

/wp-content/uploads/2015/01/del2_623075.png

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

/wp-content/uploads/2015/01/del3_623076.png

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.

/wp-content/uploads/2015/01/del4_623077.png

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.

/wp-content/uploads/2015/01/resp_623078.png

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.

/wp-content/uploads/2015/01/fault_623079.png

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

/wp-content/uploads/2015/01/workbench_623080.png

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.

/wp-content/uploads/2015/01/chrome_623081.png

To report this post you need to login first.

4 Comments

You must be Logged on to comment or reply to a post.

  1. Jessy Francis

    Thanks for the blog and for the useful information. In our project, we are also evaluating the Adapter and currently doing a PoC for the same. But facing an issue in getting the API response mapped to the Target Response structure created in ESR.

    Issue details: For .eg. we created MT_Source_Response and MT_TargetAPI_Response structures and created mapping between these two structures. From adapter logs, we can the response is received back, but when executing the response mapping is PI, an error is thrown – No value in queue to create target structure.

    Instead of MT_TargetAPI_Response, we tried using DTD and then it is working fine. When dtd is used, we could manipulate the actual response values received from API and send it back to Source system, but the same is not working with MT created.

    How do you achieve this in your scenario?

    Is there any special naming convention to follow while creating data types or message types?

    (0) 
    1. Eng Swee Yeoh Post author

      Hi Jessy

      From your description, my guess is that there is namespace issue when you use MT instead of imported DTD. You can confirm this if you copy the response payload and put it into the Test tab of your ESR mapping – your node colours next to the structure would appear red instead of green.

      When you use MT created in ESR, it normally has an associated namespace. In the message mapping, PI would expect a source payload with a namespace prefix, typically ns0. So the root element of the source payload would be something like this <ns0:MT_TargetAPI_Response xmlns:ns0=”yourMTnamespace”>

      Most likely your target API would NOT generate a response that will match nicely to the MT.

      With the Advantco REST adapter, you can use it’s format conversion feature to convert the response body from what you actually receive from the API to the one expected by the mapping when using MT.

      For my case, the API did not provide an XSD for import, so I manually created the DT/MT in ESR and used the format conversion to convert the response accordingly.

      The adapter comes with a configuration guide which should provide more details on using the format conversion.

      Rgds

      Eng Swee

      (0) 
  2. Sebastian Simon

    Hi Eng,

    Interesting Read even now nearly 1 year old.

    I used SAP’s REST adapter on a few occasions this year and it’s maturing but there are still usecases where the partner adapters make sense (authentication etc).

    Didn’t see Advantco’s Adapter for a while, the workbench looks new to me.

    The only adapter existing prior with such meta data or test features was KaTe’s RESTful adapter on receiver and sender side (as an API Console), imho even a bit simpler then as seen above, but i might be a bit biased here. As far as i know it’s the most liked feature there too 😉

    Cheers

               Sebastian

    (0) 

Leave a Reply