We’re pretty good at keeping "well-guarded" secrets at Magic Software. Sometimes we even release useful new features that few people know about. We made a lot of fanfare when we started supporting Web Services based on the SOAP protocol. In fact, I think I wrote the press release back in January 2002.
Here we are nearly 10 years later and uniPaaS now supports REST (Representational State Transfer) approaches to Web Services and few of us paid close attention when this feature emerged in the product with the release of uniPaaS 1.9e. But it is worth paying very close attention because RESTful Web Services can be accomplished without the complexity and overhead of SOAP Web Services.
REST isn’t something new at all. In fact, it is the way the Web has worked all along but with some rules added to help everyone get along.
Baiscally, a RESTful web service is a simple approach to web services implemented using HTTP and based on the architectural principles of REST. A RESTful Web Service has three resources defined:
- the URL address for the web service (you may call it a URI if you want, it is basically the same thing). The URL is the equivalent of a noun.
- the supported Internet media data type of the web service.
- the set of HTTP operations supported by the web service. Think of this as the verb.
The following table shows how the HTTP methods are typically used to implement a web service.
Unlike Web Services based on SOAP, there is no industry protocol for RESTful web services. In this sense, it is akin to a concept like Service Oriented Architecture (SOA) where a number of different approaches and protocols can be used to accomplish the objectives of the architecture. RESTful Web Services are based upon established W3C and OASIS protocols such as HTTP, URL, XML, etc. The REST architectural style is based on the idea that a client and server are interacting in a stateless manner with cached data via a uniform interface.HTTP 1.1 was designed to conform to REST. Unlike SOAP and XML-RPC, REST does not really require a new message format. Nevertheless, XML is the most popular type of REST message format. When you use XML, it becomes easier to represent the information resource in a variety of ways using XSLT and Cascading Style Sheets (CSS).
In uniPaaS 1.9e, we improved upon the ability of uniPaaS developers to employ RESTful Web Services by adding a new function: HTTPCall. This function may be used with a proxy server and supports SSL\TLS with the client certificate password protected and both basic and digest authentication schemas.
HTTPCall runs an HTTP request and returns the results. You can consume REST services by using HTTPCall with any and all verbs. This function can be used instead of the HTTPGet and HTTPPost functions, thereby simplifying implementation of RESTful Web Services in uniPaaS.
The syntax within uniPaaS for the use of HTTPCall is as follows:
HTTPCall (verb, service URL, message, [header1], [header2], …)
The “verb” is a string indicating the method. The options include GET, POST, PUT, DELETE, and HEAD. You can GET a list or a specific member of a collection. POST is like an append operation in that it adds a member to a collection. PUT replaces an entire collection or a specified member of the collection. DELETE erases the entire collection or a specific member of the collection. HEAD is a header that provides additional header information.
The “service URL” is the string that represents the HTTP address where you will retrieve the HTTP request. The HTTPCall function can easily pass a user name and password to the service URL for a secure, rights-based approach to Web Services. For example, when a uniPaaS client is accessing a web server that requires a user name and password, the URL should be HTTP://User:Password@[URL].
uniPaaS will also support secret names by following this approach: HTTP://%user_secretname%:%pass_secretname%@[URL]
Obviously, the “message” is a string with the text of the message. There is no limitation on the message content. Messages are self-descriptive and stateless.
The use of “headers” is strictly optional and you may include as many as needed. Each header may contain a string that provides additional header information as requested.
As one might expect, the HTTPCall returns a BLOB containing whatever information results from the HTTP request. If the function fails to make the connection, a blank value is returned. You can get the response headers using the HTTPLastHeader function.
Magic Software provides both Online and Rich Client sample programs that detail the use of the HTTPCall function. Look for sample programs EL23 and REL23 to get an idea of how this function can be implemented.
One of the traditional disadvantages of REST is that it doesn’t do well with complex data architectures such as those of relational databases. In this regard, using uniPaaS allows you to bridge the gap between REST and traditional databases. With uniPaaS, information is exchanged and represented using RESTful Web Services while at the same time you can store enterprise data in industry standard databases. REST advocates will simply say databases are too complex and should change to conform to the way the Web works. With uniPaaS, you avoid that argument altogether. It just works.