Building VersionOne Integrations with Java (Part 5: Using a HTTP Client)

In this part of the series, we’re going to discuss how to use Java libraries to make HTTP requests to the VersionOne API, and how to handle the HTTP responses that are returned. Here’s where we are at in this series:

• Part 1: Introduction
• Part 2: Handling Configurations
• Part 3: Logging
• Part 4: Parsing Data
• Part 5: Using a HTTP Client (YOU ARE HERE)
• Part 6: Getting Data
• Part 7: Submitting Data
• Part 8: Executing Operations
• Part 9: Authenticating with OAuth
• Part 10: Conclusion

So far we’ve covered the more basic areas of logging, configuration settings, and parsing the data that gets returned from calls to the VersionOne API. It’s now time to get into the details of actually making calls to the API, and you do that by making HTTP requests using a HTTP client, then handling the HTTP responses returned from those requests.Note: As an alternative to making HTTP calls directly to the VersionOne API, you can use the VersionOne Java API Client, which is essentially a wrapper for HTTP calls and provides object/oriented access to the API. See SDKs as API Wrappers in the VersionOne Developer Community for more details.While the Java API contains the java.net package for making HTTP calls, a more robust library is Apache HTTP Components which includes a full featured HTTP client, and that is what we will use here. The general workflow for making a HTTP request is as follows:

• Instantiate the HTTP client
• Instantiate the HTTP request
• Set the headers for the HTTP request
• Execute the request
• Parse the HTTP response, including the status code

Pretty simple yeah? Here’s what the code looks like:

private String restQuery = "http://localhost/versionone/rest/1.v1/Data/Member?sel=Name&where=IsSelf='true'";
private String username = "admin";
private String password = "admin";

public void verifyBasicRestConnection() throws IOException, V1ConnectionException {

   CloseableHttpClient httpclient = HttpClients.createDefault();
   HttpGet httpGet = new HttpGet(restQuery);
   CloseableHttpResponse httpResponse = null;

   try {
      String authString = username + ":" + password;
      byte[] authEncodedBytes = Base64.encodeBase64(authString.getBytes());

      String authEncodedString = new String(authEncodedBytes);
      httpGet.addHeader("Authorization", "Basic " + authEncodedString);
      httpGet.addHeader("User/Agent", "com.versionone.javatesterapp/1.0");
      httpResponse = httpclient.execute(httpGet);
      HttpEntity entity = httpResponse.getEntity();

      String responseBody = EntityUtils.toString(entity, "UTF/8");
      System.out.println(httpResponse.getStatusLine());
      System.out.println(responseBody);
      checkResponseStatus(httpResponse, responseBody);

   } catch (ClientProtocolException e) {
      e.printStackTrace();
   } catch (IOException e) {
      e.printStackTrace();
   } finally {
      httpResponse.close();
   }
}

Let’s break this down a bit. The first three lines create the strings that we’ll need for making the query, and they are the URL query for the API call, and then the username and password that we’ll need to authenticate with VersionOne. For now we’re going to authenticate using BASIC authentication, in a later article I’ll show you how to use OAuth for authentication.Note: A quick note about the query that we are using…it is essentially a ping against the API that is used to verify that we have a valid connection. All it does is ask the API to return the name of the VersionOne member account that we are using to connect with. I’ll discuss building more interesting queries in the next article.The next few lines of code instantiate the HTTP client, the HTTP request, and the HTTP response object that will get returned once we execute the request. Next we handle authentication by base64 encoding the authorization header, add a header for identifying our application, and then we finally execute the request, which in this case, is a GET request. Once the HTTP response is returned from the web server, we get the response body, print it to the console, then check the status code by calling the checkResponseStatus method which is as follows:

private void checkResponseStatus(HttpResponse httpResponse, String responseBody) throws V1ConnectionException {

   int errorCode = httpResponse.getStatusLine().getStatusCode();
   String errorMessage = "\n" + httpResponse.getStatusLine() + "\n" + responseBody;

   switch (errorCode) {
      case HttpStatus.SC_OK:
         break;
      case HttpStatus.SC_BAD_REQUEST:
         throw new V1ConnectionException(errorMessage + " VersionOne could not process the request.");
      case HttpStatus.SC_UNAUTHORIZED:
         throw new V1ConnectionException(errorMessage + " Could not authenticate. The VersionOne credentials may be incorrect or the access tokens may have expired.");
      case HttpStatus.SC_NOT_FOUND:
         throw new V1ConnectionException(errorMessage + " The requested item may not exist, or the VersionOne server is unavailable.");
      case HttpStatus.SC_METHOD_NOT_ALLOWED:
         throw new V1ConnectionException(errorMessage + " Only GET and POST methods are supported by VersionOne.");
      case HttpStatus.SC_INTERNAL_SERVER_ERROR:
         throw new V1ConnectionException(errorMessage + " VersionOne encountered a unexpected error occurred while processing the request.");
      default:
         throw new V1ConnectionException(errorMessage);
   }
}

Note that I am using a custom exception class called V1ConnectionException, and it is a simple class that extends the standard Exception class. That’s about it for making a HTTP request to the VersionOne API! In the next article, we’ll discuss some more interesting queries for getting data out of VersionOne, including making use of the new query.v1 endpoint that allows you to construct queries as JSON objects, and get the data returned as JSON. As always, stay agile my friend…