Table of contents

• Introduction
• Use-case description
• Technical details of the use-case
• Product mapping
• The solutions architecture
• Services layer setup
• Mediation layer setup
• API Facade layer
• The application

Introduction

The WSO2 platform is both wide and comprehensive. It can cater to almost any business IT requirement that exists today. Some of the areas where WSO2 technology keeps a strong hold includes service composition, application and systems integration, storage services, analytics, big data, enterprise security, API management and application development, among others.

Use-case description

Forest Publishing is a book store that sells books in bulk to education institutes, libraries, and other such entities. They want to have an online portal for their customers so they can process the orders with smaller quantities electronically. They will still be processing orders with larger quantities manually for various reasons. They have partnered with a payment provider and a delivery service to execute the orders.

Technical details of the use-case

The payment and delivery partners have their services offered online and API integration in their systems. The payment service is offered as a SOAP web service and the delivery service is offered as a secure REST service. Forest Publishing wants to integrate with these partners electronically and execute their business workflow. They also wants to expose the order process as an API (apart from the default application) so that any third party can use their API to build value-added services.

The sequence of the flow

The following sequence diagram shows the logical flow of the process. It shows each of the major components, what decisions and actions they take, and what responses they return.

Product mapping

The WSO2 SOA platform comprises multiple products that cover a broad range of requirements. In certain cases you might feel that two products overlap in their features. For instance you can do mediation using WSO2 API Manager, you can store messages in WSO2 Enterprise Service Bus (ESB) and you can host data services in WSO2 Application Server. As a result, selecting the right set of tools will be difficult if you are not clear about your requirements and if you do not have any background knowledge of the scenario you are trying to implement. When selecting the tools, separating out the concerns is quite important. Once you read the documentation provided by WSO2 and WSO2 library articles you might notice that if you use just the ESB you can expose APIs, do mediation, and host services and applications. However, if you separate out the concerns, each of these tasks should be done by a separate layer for reasons like better maintainability, governance, scaling, and application of quality of services.

If you consider the Forest Publishing use case, multiple layers can be identified in this; they have a business rule that needs to be enforced and multiple external services that need to be aggregated. The workflow needs to be exposed and this API needs to be integrated to a web application.

To compose the business rule, WSO2 Business Rules Server (BRS) can be used because Forest Publishing will enforce many rules during their e-commerce expansion. All these rules will need to be managed centrally, so choosing WSO2 BRS is the right move. For proof of concept, the secured delivery and payment services will have to be mocked and WSO2 Application Server can be used to deploy these mock services.

By integrating all these services a workflow needs to be created. If we analyze this orchestration, it can be seen as stateless and short running, so we do not need to use BPEL. Instead, a lightweight ESB-based mediation approach can be used. WSO2 ESB can be used to implement this workflow in the aforementioned fashion.

Once the orchestration is implemented, we need to expose it as an API to the outside world. For this requirement, WSO2 API Manager can be used. It will expose the service as an API, add security on top of it, and enable management and monitoring capabilities.

Once the API is exposed, we can create an application that will connect the API and provide the UI in order to perform e-commerce facilities. For the application, jaggeryjs - a server side javascript framework that helps build enterprise grade applications rapidly - will be used.

The solutions architecture

Services layer setup

We will setup WSO2 Application Server and WSO2 BRS in the services layer and deploy delivery, payment, and quantity check rule service, respectively. If you are trying to setup the servers in the same local machine, port offset change is something you would need to make note of.

We now need to deploy all three artifacts and test them individually using SOAPUI/REST clients. The following are requests messages for all three services.

We now need to deploy all three artifacts and test them individually using SOAPUI/REST clients. The following are requests messages for all three services.

• Payment service

  

POST https://localhost:9765/Easypay_1.0.0/services/easypay_service HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "makePayment"
Content-Length: 440
Host: localhost:9765
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)


   

   
      
         P1
         E12
         IS1245
         50
      
   

Request

  
HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8
Content-Length: 236
Date: Thu, 13 Feb 2014 19:48:38 GMT
Server: WSO2 Carbon Server


   
      
         REF4776
      
   

Response

  
GET https://localhost:9765/Deliver4U_1.0.0/services/deliver_service/deliver/uid/ABC123/pref/REF4776 HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic ZnB1c2VyOmZwdXNlcg==
Host: localhost:9765
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Request

  
HTTP/1.1 200 OK
Date: Thu, 13 Feb 2014 20:06:32 GMT
Content-Type: text/plain
Content-Length: 26
Server: WSO2 Carbon Server

REF ID : REF4776 confirmed

Response

  
POST https://localhost:9773/services/GetApprovalService.GetApprovalServiceHttpSoap11Endpoint/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "urn:getApproval"
Content-Length: 437
Host: localhost:9773
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)


   

   
      
         
            11
         
      
   

Request

  
HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 13 Feb 2014 20:13:35 GMT
Server: WSO2 Carbon Server


   
      
         
            true
         
      
   

Response

If we can test the individual services in the manner shown above, we can assume that the service layer is functioning properly.

Mediation layer setup

First, we need to register the service endpoints in the ESB so that they can be referred to from the sequences. For a production setup, the recommended pattern is to centrally define and manage the endpoint details (as opposed to hardcoding it in the synapse configuration), service contracts, and refer to them in the configuration by a key. Adding WSO2 Governance Registry to the mix will provide such governance capabilities for the deployment.

  

   

      
         1.0
      
      
         0
         0
      
   

QuantityCheck EP

  

   

      
         1.0
      
      
         0
         0
      
   

EasyPay EP

  

   

      
         1.0
      
      
         0
         0
      
   

Delivery EP

We need to boot up an ESB to compose the orchestrations. If we step back and analyze the sequence, at first, the workflow needs to talk to the rule service to obtain approval, make the payment, obtain the confirmation code, and finally provide that to the delivering service.

Similar to the endpoints, these sequences can be stored in the underlying registry/repository for better maintainability. Sequences like EasypaySeq can be re-used for different mediation flows. Therefore, storing it in a central repository increases reusability. The following are the relevant sequences.

  

   
      
         
            
               $1
            
         
      
      
         
      
   
   

   
      
   

  

   
   
      
         
            
               
                  100
                  $1
                  $2
                  $3
               
            
            
               
               
               
            
         
         
            
         
      
      
         
            
            
         
      
   

The EasyPay sequence is called with response to the rule service, hence we need to handle the true/false condition. In this sequence, we need to switch based on the response. If the response is approved (true) we execute the payment and call the EasyPay endpoint. Otherwise, we need to send an ‘approval denied’ response.

When sending the error message within this sequence, we are converting the message to a JSON payload and sending it out from the ESB.

We also specify that once we call the EasyPay endpoint the response will be picked up by the delivery sequence creating a chaining scenario.

With the response from the payment service we will directly call the delivery service to place a delivery request. We can improve this by handling payment failure cases as well.

Before sending a message to the delivery endpoint, we need to prepare the secure HTTP GET call. The sequence shows how to add the authorization headers to the request.

There will also be an out sequence defined, converting the response to a JSON output.

Now let’s test this workflow, which is registered in the ESB. Ideally, we should get a response from the delivery service for delivery confirmation if the quantity check is successful.

  
GET https://localhost:8281/fp/order/epid/E12/did/ES12/book/IS12/q/12 HTTP/1.1
Accept-Encoding: gzip,deflate
Host: localhost:8281
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Request

  
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 13 Feb 2014 21:53:41 GMT
Server: WSO2-PassThrough-HTTP
Transfer-Encoding: chunked
Connection: Keep-Alive

{"response":"REF ID : REF5415 confirmed"}

Response

If you have received the above response from the ESB the mediation layer has been completed.

API Facade layer

We can now get the endpoint that is exposed by the ESB and register that in the WSO2 API Manager’s publisher. This will apply API management and security to the service endpoint exposed by the ESB.

Once the API is published, you can discover the API, generate production keys and call the API with security using the API Manager’s store.

  
GET https://localhost:8280/fp/10/order/epid/123/did/111/book/xx11/q/10 HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Bearer a5be96e82d71a9e195d635eee6f25a
Host: localhost:8280
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Request

  
HTTP/1.1 200 OK
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
Content-Type: application/json
Date: Thu, 13 Feb 2014 22:31:53 GMT
Server: WSO2-PassThrough-HTTP
Transfer-Encoding: chunked
Connection: Keep-Alive

{"response":"REF ID : REF1155 confirmed"}

Response

The application

At this point, we have completed the entire backend that is needed to perform the book purchase and delivery transaction. Now, a web application needs to be created in order to connect to this API and provide a good user interface.

In the application, we have a certain server code that calls the API with the token. Jaggeryjs is used to write the server code in this sample. The full application code can be found at github.

Server code

Summary

The products in the WSO2 platform, such as WSO2 ESB, WSO2 Application Server, and WSO2 API Manager, among others, can be used to efficiently integrate the different layers of an enterprise application and ensures a systematic and coherent development process. The strength in performance and the agility of WSO2 products serve as a great advantage to any type of enterprise application development.