What is web service?

As tougher competition forces companies in a supply chain to work closer together, there is need to connect software in one company to another software in different company. Multiple methods have been devised to achieve this:

  • Photo by Flavio Takemoto

    the oldest method was passing data file in standardised format over proprietary or ad-hoc connection. One of the earliest effort to standardise format of data in the file used by different companies was EDI (Electronic Data Interchange)

  • as IP-based network proliferate, data file was sent over this standardised network instead, e.g. via e-mail, FTP, etc
  • as World Wide Web (WWW) gained popularity, companies realised that it could be used not only to display information in uniform manner regardless of computer platform, but it can also be used to process information uniformly across platforms. Thus born web service, which enables software to communicate among each other in real-time. In web service, the end points are called:
    • producer, for the side that provides the services, i.e. the server
    • consumer, for the side that uses the services, i.e. the client

What is RESTful web service?

RESTful web service provides powerful real-time inter-software communication via WWW technologies simply using basic HTTP (Hyper-Text Transfer Protocol) commands on Uniform Resource Identifier (URI). It got its name from REST, which stands for REpresentational State Transfer, the software architecture used by World Wide Web which enables it to serve so many purposes using simple commands. The key feature is then power through simplicity. To illustrate this, let’s see how a RESTful web service can perform all the CRUD (Create, Read, Update, Delete) transactions using basic HTTP commands.

Create record with HTTP POST command

[root@bintang ~]# telnet 10.11.12.6 80
Trying 10.11.12.6...
Connected to 10.11.12.6 (10.11.12.6).
Escape character is '^]'.
POST /ws/test HTTP/1.0
Content-Length: 35

number=3
name=Ponirah McConnaghuey
HTTP/1.0 201 Created
Date: Fri, 10 Dec 2010 14:35:53 GMT
Server: Apache/2.2.9 (Debian) DAV/2 SVN/1.4.2 PHP/5.2.13 mod_perl/2.0.4 Perl/v5.10.0
X-Powered-By: PHP/5.2.13 ZendServer/5.0
Set-Cookie: ZDEDebuggerPresent=php,phtml,php3; path=/
Location: /ws/test/3/
Vary: Accept-Encoding
Content-Length: 0
Connection: close
Content-Type: text/html

Connection closed by foreign host.
[root@bintang ~]#

Read record with HTTP GET command

HTTP GET command is the primary command used by all web browsers to display web page

[root@bintang ~]# telnet 10.11.12.6 80
Trying 10.11.12.6...
Connected to 10.11.12.6 (10.11.12.6).
Escape character is '^]'.
GET /ws/test/1 HTTP/1.0

HTTP/1.1 200 OK
Date: Fri, 10 Dec 2010 14:47:30 GMT
Server: Apache/2.2.9 (Debian) DAV/2 SVN/1.4.2 PHP/5.2.13 mod_perl/2.0.4 Perl/v5.10.0
X-Powered-By: PHP/5.2.13 ZendServer/5.0
Set-Cookie: ZDEDebuggerPresent=php,phtml,php3; path=/
Vary: Accept-Encoding
Content-Length: 141
Connection: close
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<row xmlns:xlink="http://www.w3.org/1999/xlink">
 <number>1</number>
 <name>Chuck NoRisk</name>
</row>Connection closed by foreign host.
[root@bintang ~]#

Update record with HTTP PUT command

[root@bintang ~]# telnet 10.11.12.6 80
Trying 10.11.12.6...
Connected to 10.11.12.6 (10.11.12.6).
Escape character is '^]'.
PUT /ws/test/2 HTTP/1.0
Content-Length: 25

name=Ponirah McConnaghuey
HTTP/1.0 204 No Content
Date: Fri, 10 Dec 2010 13:58:40 GMT
Server: Apache/2.2.9 (Debian) DAV/2 SVN/1.4.2 PHP/5.2.13 mod_perl/2.0.4 Perl/v5.10.0
X-Powered-By: PHP/5.2.13 ZendServer/5.0
Set-Cookie: ZDEDebuggerPresent=php,phtml,php3; path=/
Vary: Accept-Encoding
Content-Length: 0
Connection: close
Content-Type: text/html

Connection closed by foreign host.
[root@bintang ~]#

Delete record with HTTP DELETE command

[root@bintang ~]# telnet 10.11.12.6 80
Trying 10.11.12.6...
Connected to 10.11.12.6 (10.11.12.6).
Escape character is '^]'.
DELETE /ws/test/3 HTTP/1.0

HTTP/1.0 204 No Content
Date: Fri, 10 Dec 2010 14:37:41 GMT
Server: Apache/2.2.9 (Debian) DAV/2 SVN/1.4.2 PHP/5.2.13 mod_perl/2.0.4 Perl/v5.10.0
X-Powered-By: PHP/5.2.13 ZendServer/5.0
Set-Cookie: ZDEDebuggerPresent=php,phtml,php3; path=/
Vary: Accept-Encoding
Content-Length: 0
Connection: close
Content-Type: text/html

Connection closed by foreign host.
[root@bintang ~]#

Building RESTful web service

Security

Physically, web service should be placed within De-Militarised Zone (DMZ) of the network. Since it is going to be accessed by external software, it needs to insist on HTTP Secure connection implementing at least HTTP basic access authentication. Permission has to be defined on per-user basis as well, as not all users are allowed to use every web services offered.

Development tools

NetBeans Jersey
Tight integration between NetBeans IDE and Jersey framework enables quicker RESTful web service development

A separate framework is needed for the web service apart from the framework used by enterprise application. Functions that will be exposed to other software will have to be re-coded into this web service framework. The scope for this has to be thought of carefully as not all functions or features need to be exposed to external parties. It is better if the framework can come tightly integrated to an Integrated Development Environment (IDE). Such tight integration between framework and IDE will help in the following aspects:

  • for producer side:
    • automatically creating Web Application Description Language (WADL) file which describes what web services are available from this server and how to use them.
    • routing the URI to the correct handler. When someone issues the command GET /ws/salesorder/S12345678 HTTP/1.0, of course there’s actually no file named S12345678 under ws/salesorder sub-folder of the web server. Without routing, the web server will return a 404 error for file not found. Routing makes sure the requests are re-directed to the correct handlers instead
    • simplifying authentication set up
    • understanding the input, especially for create and update transactions, as it may be written in XML (eXtensible Mark-up Language)
    • error handling. The error code returned should conform to the standard HTTP status codes as much as possible
    • simplifying code organisation for each of the CRUD transactions. By default, web server only knows how to process HTTP GET command for the resources specified in the request. Web servers usually depends on programmer to explicitly define what to do on a resource if HTTP POST, PUT, or DELETE command is received. Hence the additional coding here.
    • formatting the output to be sent back to the service consumer. It can be written in XML, HTML (Hyper-Text Mark-up Language), JSON (Java Script Object Notation), plain text, etc
  • for consumer side
    • automatically generating consumer function skeleton based on WADL file provided by producer. The bulk of the consumption logic may still have to be coded manually according to the needs at each consumption point. Single producer may be used by multiple different consumers, with each consumer needing separate coding
    • easing authentication set up for each producer

Logging

In multi-party communication like this, it is generally a good idea to keep history of the conversation. Hence logging functionality should be included, both on producer and consumer sides, preferably to a database

Advertisements