WSO2 Service Integration, APIs and Application Platform: An End-to-End Use Case

  • By Nuwan Bandara
  • 9 Apr, 2014

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)

P1E12IS124550

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

  • Delivery service
  •   
    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

  • Check quantity rule service
  •   
    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.000

    QuantityCheck EP

      
    
    1.000

    EasyPay EP

      
    
    1.000

    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.

  • QuantityCheck sequence
      
    $1

    The QuantityCheck sequence creates a payload with the submitted quantity and calls the rule service for validation. The response for this message is received by EasypaySeq, which is declared as the receiving sequence in the send mediator.

  • EasyPay sequence
  •   
    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.

  • Delivery sequence
  •   
    

    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.

  • Out sequence
      
    

    Once we have the sequences ready we can create a service that associates these sequences and performs the workflow. We will use the API construct of the ESB to do this as we will be exposing a REST endpoint through the ESB.

  • ESB API construct associating the sequences
  •   
    

    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.

    About Author

    • Nuwan Bandara
    • Director
    • WSO2