PowerBuilder’s SOAP to RESTful Evolution

The movement from SOAP-based web services towards RESTful-based web services is another evolutionary journey for PowerBuilder developers and their related applications. Originally, Sybase added SOAP (Simple Object Access Protocol)-based features in PowerBuilder version 8.0. The original SOAP features were aligned with the Java implementation of EasySOAP and provided a messaging protocol specification for exchanging structured information in the implementation of web services across computer networks. Sybase enhanced the web service feature in PowerBuilder version 9.0 to include the ability to handle more complex SOAP interactions. In PowerBuilder version 11.0, Sybase then added support for Microsoft’s .NET-based web service framework as well. This greatly improved the web service interaction possibilities in that era of PowerBuilder. The .NET web service feature was tweaked again in PowerBuilder version 11.5 (and latter PowerBuilder versions) to support the newer releases of the .NET framework.

Since PowerBuilder 11.5 though, the basic SOAP-based architecture has been PowerBuilder’s “go to” vehicle for web service interactions. However, the IT industry moved onward with newer REST (Representational State Transfer) web service technology, which has now become a de facto architectural style used by most modern web services. The REST approach defines a set of constraints and properties based on the HTTP protocol that provides greater interoperability between computer systems on the Internet today. By REST using a stateless protocol and standard operations, REST systems can have faster performance, reliability, and the ability to grow, by re-using components that can be managed and updated without affecting the system, even while it is running.

There are six guiding constraints that define a RESTful system. These constraints restrict the ways that the server may process and respond to client requests so that, by operating within these constraints, the service gains performance, scalability, simplicity, modifiability, visibility, portability, and reliability. If a service violates any of the required constraints, it cannot be considered RESTful. The formal REST constraints are as follows:

1. Client–server architecture
2. Statelessness
3. Cache-ability
4. Layered system
5. Code on demand
6. Uniform interface

The focus of a RESTful service is on resources and how to provide access to these resources. A resource can easily be thought of as an object as in OOP (object-oriented programming). A resource can consist of other embedded resources as well. While designing a system, the first thing to do is identify the resources and determine how they are related to each other. This is like the first steps of designing a database: identify entities and relations. Once we have identified our resources, the next thing we need is to find a way to represent these resources in our system. You can use any format for representing the resources, as REST does not put a restriction on the format of a representation.

The client and service talk to each other via messages. Clients send a request to the server, and the server replies with a response. Apart from the actual data, these messages also contain some metadata about the message. It is important to have some background about the HTTP request and response formats for designing RESTful Web services. REST requires each resource to have at least one URI (Uniform Resource Identifier). A RESTful service uses a directory hierarchy like human readable URIs to address its resources. The job of a URI is to identify a resource or a collection of resources. The actual operation is determined by an HTTP verb. The URI should not say anything about the operation or action. This enables us to call the same URI with different HTTP verbs to perform different operations.

RESTful services do not necessarily require a document to help clients discover them. Due to URIs, links, and a uniform interface, it is extremely simple to discover RESTful services at runtime. A client can simply know the base address of the service and from there it can discover the service on its own by traversing through the resources using links. The method OPTION can be used effectively in the process of discovering a service. A primary benefit of using REST, both from a client and server's perspective, is REST-based interactions happen using constructs that are familiar to anyone who is accustomed to using the Hypertext Transfer Protocol (HTTP).

REST is also a language-independent architectural style. REST-based applications can be written using any language, be it for example: C#, Java, JavaScript, or PHP – just to name a few. If a programming language can make web-based requests using HTTP, it is possible for that language to be used to invoke a RESTful API or web service. Similarly, RESTful web services can be written using any language, so developers tasked with implementing such services can choose technologies that work best for their situation or familiar technology. 

Starting in PB 2017 R2, Appeon introduced a new RESTClient object to the PowerBuilder IDE’s System Class. Prior to PB 2017 R2, developers would need to use integrate an external DLL, .NET Assembly, or OCX-based third party software that could be called as an “interface” (OLE or External Function call by PB) to perform the RESTful actions and acting as a “broker” between the PB app and the RESTful web service. The RESTClient class in PB2017 R2 though, now enabled any PowerBuilder native client application to deal directly with a RESTful web service, thus eliminating the need for the RESTful “interface” broker components as well as requiring significantly less coding. The RESTClient object class contains many of the same functions as found in its “kissing cousin” the HTTPClient – they can perform similar actions for Request and Response heading and body information processing. What really differentiates the RESTClient from the HTTPClient is the support for the DataWindow Control, DataStore and DW Object via its Retrieve method, as follows:

Figure 1 - RESTClient object class as defined in the PowerBuilder IDE's System Class 

The RESTClient can greatly simplify the RESTful web service interaction by loading a DataWindow Object directly with the returning result set from the web service. The only restrictions are that: a) the web service is returning a JSON result set and b) the result set is two dimensional (that is, rows and columns only). If these restrictions are met, the RESTClient can be easily programmed to interact with the RESTful web service and targeted DataWindow object with just few lines of code. The following code snippet exemplifies how easy these features are to use when using the RESTClient object:

Long                      ll_rows

String                    ls_url = "http:\\<your web service url>"

DataStore            lo_ds

RESTClient           lo_rest

lo_ds = CREATE DataStore

lo_ds.DataObject = "dw_rest"

lo_rest = CREATE RESTClient

lo_rest.secureprotocol  = 5

lo_rest.timeout = 10

ll_rows = lo_rest.Retrieve ( lo_ds, ls_url )

Note that in the above code snippet, as the RESTClient’s Retrieve method is called, the resulting DataWindow Control or DataStore’s RetrieveStart, RetrieveRow and RetrieveEnd events are fired as the RESTClient handles the incoming JSON result set from the defined web service URL. This allows the PowerBuilder developer to capture response times, handle special data transformations, etc. – just like a regular DataWindow Control or DataStore that processes a DBMS result set. This approach also assumes that the DataWindow Object’s column names and data types match the web services JSON schema and that the JSON result set is basically a 2-D array. If the JSON result set is too complex, then the PowerBuilder developer can fall back to using the HTTPClient and the JSONParser to get the job done, but of course this requires some additional coding compared to the RESTClient.

PowerBuilder 2017 R3, scheduled to release in the summer of 2018, improves the RESTClient object class by allowing it to call a RESTful web service and populate a Child DataWindow object. R3 will also add support for OAuth2 tokens to the RESTClient class as well. Planned for the PB 2018 release later in 2018, further support will be added for the full CRUD (create, read, update and delete) paradigm by supporting the InsertRow, DeleteRow and Update methods for the RESTClient object class in native PowerBuilder applications.

The enhancements to the RESTClient in R3 are designed to complement the new “C# Web API” feature that is targeted for PB 2018, which will allow PowerBuilder developers to build RESTful web services using C# and the DataStore with same supporting CRUD functionality.  Developing C# Web APIs in PB 2018 should require less coding than the current .NET Web Service feature in PowerBuilder, and automatic conversion of DataWindows is also supported.