Beautiful Code [301]
27.1. Project Background
The project I'll be discussing in this chapter began with a call from one of our clients: "We need a set of Web Services to integrate our systems with one of our distributors." The client was a large manufacturer of electrical components. The system they were referring to was MAPICS, a manufacturing system written in RPG and running on their AS/400 machines. Their main distributor was upgrading its own business systems and needed to modify the way it tied into the order management system to check product availability and order status.
Previously, an operator at the distributor simply connected remotely to the manufacturer's AS/400 system and pressed a "hot key" to access the necessary screens (F13 or F14 as I recall). As you'll see in the code later, the new system I developed for them was named hotkey, since that had become part of their common language, much like the way google has become a modern-day verb.
Now that the distributor was implementing a new e-business system, it required an automated way to integrate manufacturer data with its own system. Since this was just a single distributor for this client, albeit the largest, the system also needed to allow for the future addition of other distributors and whatever protocols and requirements they might have. Another factor was the relatively low skill level of the staff that would maintain and extend this software. While they were very good in other areas, Java development (as well as any kind of web development) was still very new to them. So, I knew that whatever I built had to be simple and easy to extend.
Integrating Business Partners the RESTful Way > Exposing Services to External Clients
27.2. Exposing Services to External Clients
Prior to this project, I had delivered several technical presentations to user groups and conferences regarding SOAP (Simple Object Access Protocol) and web service architecture. So, when the call came in, it seemed I'd be a natural fit for what the client was looking to accomplish. Once I understood what they really needed, though, I decided that they would be much better off with a set of services exposed through simple GET and POST requests over HTTP, exchanging XML data describing the requests and responses. Although I didn't know it at the time, this architectural style is now commonly referred to as REST, or Representational State Transfer.
How did I decide to use REST over SOAP? Here are a few of the decision points to consider when choosing a Web Services architecture:
How many different systems will require access to these services, and are all of them known at this time?
This manufacturer knew of a single distributor that needed to access its systems, but also acknowledged that others might decide to do the same in the future.
Do you have a tight set of end users that will have advance knowledge of these services, or do these services need to be self-describing for anonymous users to automatically connect to?
Because there has to be a defined relationship between the manufacturer and all its distributors, it is guaranteed that each of the potential users will have advance knowledge of how to access the manufacturer's systems.
What kind of state needs to be maintained throughout a single transaction? Will one request depend on the results of a previous one?
In our case, each transaction will consist of a single request and a corresponding result that doesn't depend on anything else.
Answering the above questions for this project yielded the obvious choice of simply exposing a set of known services over the HTTP protocol and exchanging data using a standard e-business protocol that both systems could understand. If the manufacturer would have liked to allow anonymous users to query product availability, then I might have opted for a full SOAP solution because that would allow systems to discover the services and programmatically interface with them without prior knowledge of the systems.
I currently work in the