Consuming a RESTFul web service with Java Part 1 (java.net way)

Its incredible how common RESTFul web services have become now, i mean i have only started hearing about them in the last couple of years and the usage surge is a little interesting, especially since the style was originally proposed by Roy Fielding back in 2000. I guess one of the reasons could be all the big players getting onboard the REST bandwagon, but anyway this post is not about an analysis of the "RISE Of The REST", its really about how to consume them. If you want to know more about how REST works have a read of this post by Stefan Tilkov. 

Ok so now there have been two projects where i have had to write REST clients, projects such as:

1. Data capture automation tool: This was a java client i wrote for the School of Chemistry at UNSW, which basically helps them upload their experiments data to a server via a web service. I loved this project, i mean i had a chance to do commercial Swing programming, how often does that happen? ohh and i also had a chance to flex my threading muscles.  The entire source code for this project is available here
2. Location project: So this one is still in development, and i have not exactly decided to push the source code out for this one yet, but it basically consumes the Google Maps API.

Ok, so I am sure that I have not explored all possible ways of consuming web services in Java, but I did get a chance to play around with 3 possible methods of doing this, and i am going to talk about the first method in this post.

Problem

How do we consume a RESTFul web service in java?

Solution

Ok so for this one we will focus on using the classes from the java.net API

first lets start with a simple example of how to open the connection using some of the classes from the API, so here;s a little example, which could be the main method of pretty much any class
    /*
     * for the sake of this tutorial, we will avoid trapping
     * specific exceptions
     */
    public void simpleConnection()throws Exception
    {
            String path ="http://this/is/your/path/to/the/service";
            java.net.URL url = new java.net.URL(path);
            /* open the connection */
            java.net.HttpURLConnection con = (java.net.HttpURLConnection)url.openConnection();
            /* lets check if the connection was successfully opened */
            if (con.getResponseCode() != java.net.HttpURLConnection.HTTP_OK) {                   
                throw new RuntimeException(
                        "Error calling Search API (HTTP status " + con.getResponseCode() + ")");
            }    
            /* get the incoming data */
            java.io.InputStream stream = con.getInputStream();
    }

Ok so the example above would open a connection and get the input stream, from which we can read the data. now chances are that a lot of the time we would need to call the web service using som e parameters. So how do we do that? well its simple, we simply pass the parameters in the path variable like this

String path ="http://this/is/your/path/to/the/service?param1="+
                java.net.URLEncoder.encode("value1","UTF-8")+
                "&param2="+java.net.URLEncoder.encode("value2","UTF-8");

Now onto the last bit, there is a possibility that your connection may go through a proxy server and in that case the above code sample would throw an error unless we account for the presence of the proxy server. So we accomplish that by letting our program know of the proxy server via System properties.

        java.util.Properties systemProperties = System.getProperties();
        systemProperties.setProperty("http.proxyHost","your-proxy.url.com");
        systemProperties.setProperty("http.proxyPort","1234");

ok so the overall method with the query parameters and the proxy bypass would look something like this

    public void queryWithParamsAndProxy()throws Exception
    {
        java.util.Properties systemProperties = System.getProperties();
        systemProperties.setProperty("http.proxyHost","your-proxy.url.com");
        systemProperties.setProperty("http.proxyPort","1234");

        String path ="http://this/is/your/path/to/the/service?param1="+
                java.net.URLEncoder.encode("value1","UTF-8")+
                "&param2="+java.net.URLEncoder.encode("value2","UTF-8");
      
        java.net.URL url = new java.net.URL(path);
        /* open the connection */
        java.net.HttpURLConnection con = (java.net.HttpURLConnection)url.openConnection();
        /* get the incoming data */
        if (con.getResponseCode() != java.net.HttpURLConnection.HTTP_OK) {                   
            throw new RuntimeException(
                    "Error calling Search API (HTTP status " + con.getResponseCode() + ")");
        }    
        /* get the incoming data */
        java.io.InputStream stream = con.getInputStream();
    }