The present post does not pretend to explain technical functionalities about de REST Adapter, it tries to analyze if the Adapter is fully compatible with RESTful services. If you want to know more about the technical details, I highly recommend to you the Ivo Kulms’s blog. This blog explains the functionality of the REST Adapter with practical cases and had help me a lot to understand it.
First of all, we need to understand what it a RESTful web service. For that purpose, I recommend the reading of the Martin Fowler’s article about the “Richardson Maturity Model”.
Many people call “REST service” to a HTTP POST operation with a JSON message, but it is far to be a RESTful service.
So, how much “RESTful” is the REST Adapter? Let’s explore the capabilities of the Sender and Receiver sides of the REST Adapter following the Richardson Maturity levels:
Level 0: The Swamp of POX
The REST Adapter is based in the HTTP protocol (for HTTP and of course HTTPS communications), so this basic level is supported:
But, there is a limitation… Theoretically the data could be exchange in any format (XML, JSON, YAML, etc.), but the Adapter is limited to JSON and XML in both sides (Sender and Receiver):
Level 1: Resources
The Adapter supports resources in both sides, even with several resource levels. It is a strong capability.
There are many ways to assign values to these variables (“slot_id” in the example): Constant, XPath expression, JSON expression, Dynamic Configuration, etc.
Level 2: HTTP Verbs
The Adapter is designed to support CRUD operations (GET, POST, PUT, DELETE):
In the “Operation Determination” tab, it is possible to map the HTTP operations with the PI operations:
In the “REST Operation” tab, there are different ways to define the HTTP operation. The easier one, is the “Manual Value” option:
But, what about PATCH? The use of the PATCH operation is growing up, what happens if you need to invoke a RESTful web service with a PATCH operation? If it is mandatory for you, you need version 7.50 >= SP09, as explained in the following SAP note:
And, in addition, what about the use of different HTTP response codes (201, 202, 404, 409, etc.)? For this purpose, you can use the “Error Handling” tab for both Adapter sides. You have more information about this functionality in help.sap.com. Also, for this functionality, maybe you need to apply the patch described in the following SAP note:
Level 3: Hypermedia Controls (HATEOAS)
There is not any standard functionality related to HATEOAS in the REST Adapter. However, from my point of view, this is not a big problem, because the links are part of the payload and the payload could be modified in different ways.
If you call a system or application and receive a response payload like this one:
<slotList> <slot id = "1" doctor = "jsmith" start = "1000" end = "1005"/> <slot id = "2" doctor = "jsmith" start = "1015" end = "1020"/> </slotList>
It is not very difficult to include links in the response Mapping:
<slotList> <slot id = "1" doctor = "jsmith" start = "1000" end = "1005"> <link href = "/slots/1"/> </slot> <slot id = "2" doctor = "jsmith" start = "1015" end = "1020"> <link href = "/slots/2"/> </slot> </slotList>
In the same way, if you receive links in the response payload from a RESTful service and the sender needs them, you can use mappings to adapt received links to the sender format. In that case, the easier way to resolve this problem, could be trying to use the same relative URLs in both sides (receiver and sender).
Now, we can try to answer the initial question: How much “RESTful” is the REST Adapter? From my point of view, pretty much. Apart from some non-critical limitations (message formats not supported as YAML, PATCH operation in low versions, HATEOAS…), the REST Adapter functionality is enough to resolve the integration with the most cases of REST services.
Note: For writing this article, I have used SAP PI 7.31 SP18.