Friday, December 30, 2011

How to extract HTTP header fields in a REST API

To be able to extract HTTP headers fields from incoming requests accessing a REST API is particularly useful when trying to log the transactions that are coming through the REST based service.

In this example, I use Java based JBoss RESTEasy together with @Context java annotation to extract the header information.

One of the REST API operation is /version that returns the current version of the API in a JSON format.The interface operation is defined as follow:


     * Get the current version of the REST API.
     public Response getVersion(@Context HttpHeaders headers);

The @Context annotation allows you to map request HTTP headers to the method invocation.

One way to safely extract all available header parameters is to loop through the headers.The method getRequestHeaders from returns the values of HTTP request headers. The returned map is case-insensitive and is read-only.

   if (headers != null) {
       for (String header : headers.getRequestHeaders().keySet()) {

When querying the REST API via a browser:

you obtain a minimum set of headers fields:

   Header:cache-control Value:[max-age=0]
   Header:connection Value:[keep-alive]
   Header:accept-language Value:[en-us,en;q=0.5]
   Header:host Value:[]
   Header:accept Value:[text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8]
   Header:user-agent Value:[Mozilla/5.0 (Windows NT 6.1; WOW64; rv:8.0)    
   Gecko/20100101 Firefox/8.0]
   Header:accept-encoding Value:[gzip, deflate]
   Header:session-id Value:[d636369c]
   Header:accept-charset Value:[ISO-8859-1,utf-8;q=0.7,*;q=0.7]

To be able to extract a specific header field (e.g. Host), you can use the getRequestHeader function:

 public Response getVersion(@Context HttpHeaders headers) {
     if (headers != null) {
        List<String> hostHeader = headers.getRequestHeader("host");
        if (hostHeader != null) {
           for (String host : hostHeader) {
     // Get the version
     final Version current_version = new Version();
     final ObjectMapper mapper = new ObjectMapper();
     final JsonNode rootNode = mapper.createObjectNode();
     ((ObjectNode) rootNode).putPOJO(Version.XML_ROOT_ELEMENT, current_version);
     final ResponseBuilder builder = Response.ok(rootNode);

If you are using a test harness tools like cURL, you can also easily add additional HTTP header fields
(e.g. the email address of the user making the request or the referer) and test the logging functionality of your REST API:
curl -H "From:"
curl -H "Referer:"

The headers can also be obtained through the HttpServletRequest object.
This can be done using the @Context HttpServletRequest annotation and can provide additional information about the incoming request:

public Response getVersion(@Context HttpServletRequest request) {

Since HttpServletRequest extends ServletRequest you also getting useful methods providing information on the Internet Protocol (IP) address, host and port of the client or last proxy that initiated the request.

public Response getVersion(@Context HttpServletRequest request) {

Monday, November 28, 2011

cURL setup and OpenSSL

In a previous post I was explaining how to use cURL to quickly test REST web services. If your web service has to be secure, you are probably using Transport Layer Security (TLS) - the new Secure Sockets Layer (SSL) cryptographic protocol.

To be able to use TLS/SSL with cURL, you will need to have some SSL libraries/DLL such as OpenSSL installed. If you did not install OpenSSL, you will most likely get the following error when trying to use cURL:

"The program can't start because LIBEAY32.dll is missing from your computer. Try to reinstall the program to fix this problem."

To fix this, you can either install the OpenSSL on your machine, or if you just want to install the minimum, you can just copy the following DLLs from OpenSSL (I am using OpenSSL 1.0.0c) to your cURL folder:
  • libeay32.dll
  • ssleay32.dll
By the way, you can download cURL for most of the OS and platforms and usually SSL and non SSL versions are available for each OS (see current windows versions below):

Friday, October 28, 2011

Combining IHE transactions : Orchestration or Choreography?

Integrating the Healthcare Enterprise (IHE) has gained tremendous momentum in the past few years. Started as a Healthcare Information and Management Systems Society (HIMSS) and Radiological Society of North America (RSNA) workshop in October 1998 with only 15 participants including AGFA, Cerner, Fuji, GE, HP, Philips, Siemens, the IHE initiative has more than 400 members worldwide. It is composed of healthcare professional associations, government agencies, Health Information Exchanges (HIE), healthcare providers, IT and consulting companies, trade, educational, standard and research organizations. IHE provides a standards based-interoperable framework to share and exchange information between healthcare organizations across networks.

Combined with the latest technology and well established standards (HL7, DICOM, IDC9/10, LOINC, W3C), clinical data can then be securely and privately accessed and transmitted locally between network endpoints (e.g. within the same hospital between the practices and a lab). IHE profiles can also be used across Health Information Exchanges (HIE) of Regional Health Information Organization (RHIO), or a state level (e.g. an individual state in the US, Canada or Europe), or at the federal level (e.g. the US Nationwide Health Information Network or NwHIN). As a result, there is a strong need to integrate and combine individual IHE profiles end-points to form “hub of hubs” or “network of networks” to support health information exchange between the participating nodes entities.

Because IHE transactions are most likely to be offered as web services, combining those transactions can be done following Service Oriented Architecture (SOA) and Service Oriented Computing (SOC) principles.

Conventional middleware distributed system infrastructures (e.g. JMS) are generally not sufficient or flexible enough to mediate, transform, federate and route messages from and to web services.

Enterprise Application Integration (EAI) goes one step ahead, trying to separate the applications from the web services end-points. EAI usually employs a centralize service broker for this, a set of connectors and an independent data model. Services can then send and subscribe to receive messages to and from the broker. However, this very centralized approach requires a large amount of up front development and business process design for the connectors, as well as high cost of maintenance in general. Enterprise Service Buses (ESB) is an infrastructure that leverages EAI principles.


Like EAI, orchestration uses a centralized approach. Web services orchestration is realized through Business Process Execution Language (BPEL) that describe the collaboration and interaction between the web service participants.

Business workflows, states, actions, events, control flows and exception handling can be specified. Messages can be received and sent directly from and to WSDL ports. Results received asynchronously from web services can be combined to create new messages. Usually BPEL workflows are created and updated with visual design tools.

There is often an overlap between orchestration engines and Enterprise Services Buses (ESB). Vendors now also offer BPEL design on top of more generic EAI mechanisms enabling true orchestration for ESBs.


Choreography is more distributed and collaborative in nature and uses the Web Service Choreography Interface (WSCI) specification and the WSDL description files to represent the flow of messages exchanged between the Web services involved.

Choreography seems more flexible than orchestration since it does not rely on a central element that could become a bottle neck and seems to offer more complex interaction potential between web services. However, choreography has some drawbacks including the necessity for all web services to be aware of overall business process workflow. WSCI itself does not specify the definition and the implementation of the mechanism to implement the message exchange.

In addition to this, performance can be an issue if high volume message transactions between the end-points peers are not handled properly.

Moreover, there is no clear responsibility for the overall workflow leading to legal issues related to monitoring and maintenance.

Orchestration vs Choreography

Orchestration also has the advantage to be a much more mature integration technology than choreography. For these reasons, most of the state-wide health information exchange networks in the US employ a Service-Oriented Architectural (SOA) model that is implemented through an Enterprise Service Bus (ESB) orchestration.

In addition to this, web service orchestration offers much more than just technical benefits:
  • Organizational: standardization, narrow gap between business analysts and developers;
  • Managerial: risk reduction, lower costs, more flexibility;
  • Strategic: IT resilience, delivery time reduction, less technology lock-in;
  • Technical: portability, reuse, interoperability of tools, less complex code, better maintainability;
  • Operational: efficiency, automation, higher level tasks management.
When deployed on high performance platforms such as SOA software appliances, orchestration solutions are easy to test, extend and maintain.

  • More on this topic to be published as part of the following paper: Andry F., Wan L., HEALTH INFORMATION EXCHANGE NETWORK INTEROPERABILITY THROUGH IHE TRANSACTIONS ORCHESTRATION, 5th International Conference on Health Informatics (HEALTHINF 2012).

Friday, September 23, 2011

cURL tests harness and TLS

In a previous post, I have explained how to use cURL to test harness REST based Web services. One thing I did not described was how to add Transport Layer Security (TLS) in your tests. In other words, how to successfully test REST Web services over HTTPS?

The cURL manual describes a certain number of options that can be used. One of the most convenient option is -k or --insecure. It allows curl to  perform  "insecure" SSL connections and transfers. All SSL connections are attempted to be made secure by using the CA certificate  bundle  installed by  default. So if you SSL connection does not require client side authentication it is a very quick way to test your web service over SSL:

  curl -k

Another useful option can be used if in conjunction to SSL, you need to compress your payload via GZIP for example to optimize the transfer of large messages. In this case, you will use the option -H or --header that will help you specify custom headers to your request:

  curl -H "Accept-Encoding: gzip,deflate" -k

Notice in that case that the -k or --insecure option is always placed just in front of URL.

Of course, other headers such as the one described previously can be combined:

  curl -c ./cookies.txt --data-binary @login_password.json -H "Content-Type: application/json" -H "Accept-Encoding: gzip,deflate" -k

Wednesday, August 31, 2011

Medication Adherence - How technology can help?

Looking for ideas to reduce the rise of health care cost? Easy! Ask patients to swallow their medication!

According to recent studies, the lack of prescription medication adherence cost between $250 and $300 billion annually, including $100 billion in hospitalization. For example, it is estimated that in the US 89,000 deaths annually are due to non adherence to anti-hypertensive treatments. This problem is particularly acute for patients with coexisting conditions who take a variety of medications sometimes prescribed by different physicians.

Obviously doctors and pharmacists have a critical role to encourage patients and caregivers to administrate medication correctly and rigorously.

Cost is not necessarily the main factor: even when drugs are free, adherence rate is 60% in the US and only %50 in developed countries. In other words, improvements in co-payments structures will only partially improve adherence. Another area of possible improvement will be the use of fee-for-service model.

Another way to improve medication adherence is the proper use of specific technologies:

Here are some suggestions:
  • the integration of practice EMRs systems and pharmacies via HIE solutions (a lot of practices are still using paper).
    • online incentive programs (e.g. provided by the employers) to promote prevention, quality of life and best practices in therapy. It is recognized that financial incentives and other rewards when well designed and targeted can improve adherence (smaller and higher reward frequency is usually more efficient than big and sporadic rewards).
    • advances in personalized medicine can help taylored medication intake and increase medication adherence
    With the amount of money at stake, I am sure there is a large number of companies, including start-ups, who are working hard on this problem. So stay tune!

    Finally, we have to keep in mind, that other factors including lifestyle, psychological issues and health literacy play an important role as well. And these are not negligible!

    Friday, July 29, 2011

    How to test secure web services with soapUI - part #2

    In  a previous article I described how to specify signature and encryption for outgoing Secured Web Services request.

    1. SAML

    In this second article I will talk about SAML and incoming Secure Web Service responses.

    If you are using SAML 1.X then you just need to add a SAML 1.X assertion in the corresponding window.
    You may have to add a timestamp as follow:

    In this example, we specify 10,000 milliseconds (10 seconds) for the life time of the Timestamp:

    SAML 1.X assertions are copied and pasted in the SAML tab:

    Of course, if you combine signature and encryption with SAML 1.X. You can those to the configuration tabs as well.

    For SAML 2.0, the only option you have for this version of soapUI is to add it manually to the WSSE section of your SOAP request:

    2. Incoming Secure Web Service 

    Setting up incoming secure Web services responses encrypted and/or signed is easier than for outgoing request:

    1) Make sure that you have Keystores / Certificates tab set - You probably have done that earlier as described in part #1 of this article.
    You verify the signature with public key contained in the server's sender certificate/store and your private key to decrypt what the other server sends you.

    2) Create an incoming WSS configuration (e.g. my_config_from_server_A) that will decrypt the incoming SOAP requests coming from server A:

    You specify that you want to use your keystore to decrypt the message and the server's certificate/store to verify the signature of server A
    (theses should appear in the drop box for each field):

    3) Last, you want to specify that you are using the incoming configuration for each request:


    Monday, June 27, 2011

    Problem initializing the class javax.crypto.SunJCE_b with soapUI ?

    Last week, I have decided to download and  install the lastest soapUI PRO version 4.0 from Eviware.
    I have been using soapUI for some time to test secure SOAP Web services using SSL/TLS as well as encrypting and signing the SOAP payload.

    However when I tried to use my existing projects I end-up with the following errors in my soapUI log:

    Wed Jun 22 11:43:05 PDT 2011:ERROR:java.lang.NoClassDefFoundError: Could not initialize class javax.crypto.SunJCE_b
       java.lang.NoClassDefFoundError: Could not initialize class javax.crypto.SunJCE_b
        at javax.crypto.KeyGenerator.a(DashoA13*..)
        at javax.crypto.KeyGenerator.(DashoA13*..)
        at javax.crypto.KeyGenerator.getInstance(DashoA13*..)
        at com.eviware.soapui.impl.wsdl.submit.filters.WssRequestFilter.filterWsdlRequest(
        at com.eviware.soapui.impl.wsdl.submit.filters.AbstractRequestFilter.filterAbstractHttpRequest(
        at com.eviware.soapui.impl.wsdl.submit.filters.AbstractRequestFilter.filterRequest(
        at com.eviware.soapui.impl.wsdl.submit.transports.http.HttpClientRequestTransport.sendRequest(
        at java.util.concurrent.Executors$ Source)
        at java.util.concurrent.FutureTask$Sync.innerRun(Unknown Source)
        at Source)
        at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(Unknown Source)
        at java.util.concurrent.ThreadPoolExecutor$ Source)
        at Source)

    A quick search on the web told me to check if my some of my security setup in my JRE was properly configured.
    For this it was recommended to check the security directory under the lib folder (.\Java\jre6\lib\security):

    I also checked the content of the content of the jar file ./Java/jre6/lib/jce.jar which should contain the missing class in question:  javax.crypto.SunJCE_b

    However everything looked fine. Even though my JRE was almost up-to-date, I finally managed to fix this issue by upgrading my java JRE to the latest version!

    Tuesday, May 31, 2011

    How to test secure web services with soapUI - part #1

    Recently I have been involved in a SOA project which goal is to orchestrate  IHE integration profiles SOAP web services (XCPD & XCA) using an enterprise service bus (ESB).

    The security characteristics of these web services include digital certificates for transport level security two-way transport layer security (TLS),  message level security (encryption and digital signature) as well as single sign-on (SSO) based authentication using SAML 2.0 assertions.

    One of the challenges was to find a tool we could use to create test harness for these web services, but also to simulate and mock some of these same services during development and testing.

    For this I used soapUI. Overall it was not too complicated, except the support for SAML 2.0 since the current version of soapUI (4.0) only supports SAML 1.1 out-of-the-box.

    Initially security features on the XCPD web service were  turned off so we could test the basic SOAP web service functionalities. For this a new soapUI project was created by introspecting the XCPD service Web Services Description Language (WSDL) file:

    To make the initial project simple, no test suite has been created and the initial operation has been re-labelled "RespondingGateway_XCPD" and its sample request has been modified to query a specific test patient (Joan Hunter) and renamed XCPD_PATIENT_JOAN_HUNTER:

    The test is done by submitting the request to the XCPD end-point:

    This returns in the response window the XCPD response.

    In the next steps, we will setup all the security features for querying our XCPD service :
    The SAML 2.0 assertion will be described in the part two of this post.

    1. TLS setup

    First we need to indicate that we are using SSL on top of HTTP for the transport layer. For this we need to setup the client keystore via file/preference/SSL settings (from the machine where soapUI will run):

    2. Message level security

    Probably the first thing you want is to specify your keystores and certificates if you decide to have mutal secure communication. You will use your private key from your key store (my_key_store.jks) to sign messages you send and decrypt the payloads you receive, and you will use specific server public key/certificate (a_another_server_keystore.jks) to encrypt the SOAP messages you send and verify signatures you receive. The server with whom you have secure mutual communication will do the reverse.

    The soapUI message level security configuration for SOAP (WS-security) can be setup by selecting our soapUI project XCPD_Tests, right-click and select Show Project View and then add using the sign + in the out-going WS-Security configuration :


    You then specify your configurations (e.g. my_config_to_server_A) for outgoing messages and similarly to ingoing messages.

    Here how you would define a configuration in the Outgoing WS-security Configurations tab:

    1. add a signature tab a
    2. add an encryption tab (is you also use SAML 1.1 you would also add a SAML tab and a timestamp tab before adding the signature and the encryption).

    2a. Signature

    In the Signature tab, you specify:
    • the keystore that contain the private key to sign the messages you are going to send (usually your private key - expect if you want to mock another server)
    • the alias for the key to use for signature
    • the certificate password
    • the key identifier type (none, binary security token, X509 certificate or subject key identifier)
    • the signature algorithm (e.g SHA256)
    • the signature canonicalization
    • the number of certificates used to sign
    • the parts you want to sign (e.g. the content of the body of namespace

        2b. Encryption

        In the Encryption tab, you specify:
        • the public key of the server you are sending your SOAP messages to
        • the alias for the key to use for encryption
        • the certificate password
        • the key identifier type (none, binary security token, Issuer Name and Serial, X509 certificate, subject key identifier, Embedded KeyInfo, Embedded SecurityToken Reference, Thumbprint SHA1 Identifier)
        • an embedded key name (if any)
        • an embedded key password (if any)
        • a symmetric encoding algorithm
        • a key encryption algorithm 
        • the encryption canonicalization
        • the number of certificates used to sign
        • the parts you want to encrypt (e.g. the content of the body of namespace

        And finally, last but not least, you need to specify for the request which outgoing security configuration you want to choose. In our case we have defined only one configuration: my_config_to_server_A at the project level. To select the configuration, click on the Auth Tab at the bottom of the request window, select in the drop-down Outgoing WSS field your configuration. Create and configuring incoming Secure Web Services will be very similar.

        You are now ready to test your SOAP Web Service with soapUI!

        In  part #2 we will look how SAML can be added to the mix.

        Thursday, April 28, 2011

        How to test harness REST web services with cURL

        cURL is a very convenient command line tool to send and retrieve data using the URL syntax. It supports a large number of protocols: HTTP, HTTPS, FTP, FTPS, SCP, SFTP, TFTP, LDAP, LDAPS, DICT, TELNET, FILE . IMAP, POP3, SMTP and RTSP.

        I have been using cURL for quickly and conveniently testing RESTFul APIs.

        Since I am doing most of my development on Windows platforms, I am using cURL in conjunction with Console, a Windows console window enhancement tool.

         First you need to download and install cURL for your platform (windows, Linux ect). Then you can do a quick test by accessible the home page of your favorite web site:

        This should display the HTML content of the home page. At this point I would suggest to look at the documentation to see what you can do with cURL including the FAQ.

        I usually use simple test harness such as 'curl' if you REST API exposes available versions.

        You can then start to do more sophisticated tests such as authentication credentials from files (in my case I use a JSON data structure to automatically authenticate to my web service), saving cookies on files (using the the -c option):

        curl -c ./cookies.txt --data-binary @login_password.json -H "Content-Type: application/json"

        With my JSON file as follow: {"login":{"username":"user1","password":"StrongPassword1"}} 

        The cookie in my case contains a session token that I can reuse between each cURL calls. In the next call I read the cookie (via the -b option):

        curl -b ./cookies.txt

        The output of the command can be saved in a file using the option -o or redirecting our output:

        curl -o google.html


        curl > google.html 


        In my next post on this topic, I will explain how to use SSL/TLS and specify GZIP headers to your cURL requests.

        Thursday, March 31, 2011

        JUnit based integration testing with Simple JNDI

        I regularly use TJWS  a light weight Java Web Server build as a servlet container to provide standard Web Server capabilities at building and testing time.

        The main advantage is that I don't have to deploy my war file to my production server (e.g. JBoss) to test my Java Web application. My maven build runs complex integration JUnit tests immediately after building the war file with maven.

        In my configuration however, I have to use JNDI (Java Naming and Directory Interface) to connect to a specific datasource (DB2 via JDBC) for some of  my tests.

        I used Simple JNDI for this which also offer an easy and elegant way to configure data source access.

        Here are the steps I follow to setup my JUnit tests using Simple JNDI:

          • Add dependencies in Maven 2 Pom file for Simple JNDI, java persistence and DB2 JNDI/JDBC:

          • Create a small Java class for the JNDI setup
               import javax.naming.InitialContext;
               import javax.sql.DataSource;
               public class JndiSetup { 
                    * Setup the Data Source
                   public static void doSetup(String ds_name) {
                       try {
                           InitialContext ctxt = new InitialContext();
                           DataSource ds = (DataSource) ctxt.lookup("jdbc."+ds_name);
                           // rebind for alias if needed
                           ctxt.rebind("jdbc/"+ds_name, ds);
                       } catch (Exception ex) {

          In more complex situations, you may have also to create an EntityManager and use an EntityManagerFactory.

          • In the JUnit java script code, setup your JNDI connection before running your tests:
               public static void setUpClass() throws Exception {

          • Create a file in the "\src\test\resources" path in your project 

          • Create a file in the "\src\test\resources\config" path in your project (I am using an IBM DB2 data source). Create the config directory if it doesn't exist. The "config" name comes from parameter in file. If you want a different name, "foo", for the folder, make sure to update the "" property and create a "foo" folder in "\src\test\resources" path. Make sure the directory /src/test/resources is in the Java build path, and the output folder is set to target/test-classes

          With all of this you should be ready to test your integration using >mvn clean install.

          You may have also to do a >mvn eclipse:eclipse -DdownloadJavadocs=true as well if you are using Eclipse and your new dependencies and imports do not work properly.

          Monday, February 28, 2011

          REST-Style Architecture and the Development of Mobile Health Care Applications

          Mobile devices offer new ways for users to access health care data and services in a secure and user-friendly environment. These new applications must be easy to create, deploy, test and maintain, and they must rely on a scalable and easily integrated infrastructure.

          In the ambulatory health care environment, providers spend the majority of their time in an examination room with patients. Although some clinics have installed personal computers in the exam room for use at the point of care, many physician practices have yet to do so or have no such intention. Reasons for not installing PCs in the exam room include (among others) lack of space, security concerns, and cost. Often, clinics have PCs installed outside of the exam room to be used for encounter documentation or health history research (i.e., reviewing the patient's health records). This physical setup is often satisfactory for providers to complete their documentation needs. Providers often scratch rough notes on paper during an encounter, then dictate or type their notes after the visit has ended. The absence of computers in the exam room, however, is a disadvantage for research activities. Frequently, after listening to the patient's verbal health history, a provider wishes to read past records. If those records are in an electronic format, it is optimal to access those records at the point of care (i.e., in the exam room).

          Thus, computer devices that are smaller and more mobile than a PC (e.g., smart phones, PDAs, tablets) would be the optimal hardware choice to access these electronic records. Given that many physicians carry smart phones, such mobile devices would be the ultimate tools to look up patient records.

          Since the development of client applications on different mobile platforms requires more time than creating web applications for a handful of browsers, it is important to minimize the complexity of the integration with the back-end services and legacy systems and to try to decouple the development and maintenance of the client- and server-side components.

          The Representational State Transfer (REST) architecture is an alternative to SOAP and offers clear advantages over SOAP including lightweight architecture, extensibility, scalability, easy of development, testing, deployment and maintenance.

          REST API prototypes can be created in a matter of days and a full functioning set of sophisticated clinical based web services accessible by mobile client applications within few weeks.

          In addition to this, REST APIs are particularly suitable for fast and loosely-coupled solution integration such as mobile applications, but can also be used in health care for portal and mash-up applications as well.

          Andry F., Wan L., Nicholson D., A mobile application accessing patients' health records through a REST API, 4th International Conference on Health Informatics (HEALTHINF 2011), pp 27-32, Rome 2011.

          Saturday, January 29, 2011

          Increase your productivity on Windows platforms with Console

          A couple of years ago, one of my colleagues showed me Console, a very useful and nice Windows console window enhancement tool. Since then I have been using it and increased my productivity when it comes to command line tasks on Windows platforms. This is an open source software available on Source Forge.

          With Console, you have all your Windows consoles within a single application - you also get:
          • multiple tabs
          • text editor-like text selection
          • different background types
          • alpha and color-key transparency
          • configurable font, different window styles
          As a result, you can customize each console that appear in different tabs.

          In the example below, I have created a Tab called "MY-MAVEN-BASED-PROJECT" that opens at a specific windows path with a particular prompt: "PROJECT-ROOT:" to build your project.

          To configure your prompt, you need to do the following:

             In the console settings tab, go to the shell field and enter:

                      cmd.exe /k "prompt <your-prompt>"

          and for the startup directory, just specify the directory where you want to open your customized tab.

          You can select your background color and style in the background customization tab: