In this part of the series, we’re going to discuss how to incorporate data parsing in your integration.

Here’s where we are at in this series:

So far we’ve talked about some of the more basic aspects of building a VersionOne integration with configurations and logging. Yet another basic building block of an integration is the ability to parse data. When I refer to data parsing, I am specifically referring to parsing the data that is returned when making an API call (or query), whether it be to the VersionOne API or the API of a third-party system.

Many modern APIs are implemented as RESTful APIs and typically return data in either a XML or JSON format. The VersionOne API provides both formats, and the format that is returned depends on the API endpoint that you are using. If you want to get your data in a XML format, you would use the rest-1.v1/Data endpoint, and for JSON, you would use the query.v1 endpoint.

Note: We’re not quite ready dig too deeply into the API details (that will happen in part 6), but if you’re interested you can learn more about the various VersionOne endpoints that are available at the Developer Community site here:

For example, here’s what the data looks like when requesting information about a Story in a XML format from the VersionOne API:

<Asset href="/versionone/rest-1.v1/Data/Story/1159" id="Story:1159">
  <Attribute name="Name">Customer Profiles</Attribute>
  <Relation name="Status">
  <Asset href="/versionone/rest-1.v1/Data/StoryStatus/135" idref="StoryStatus:135"/>
  <Attribute name="Status.Name">Done</Attribute>

Now here’s its equivalent in JSON:

      "_oid": "Story:1159",
      "Name": "Customer Profiles",
      "Status": {
      "_oid": "StoryStatus:135"

For the rest of this article, I’m going to focus on parsing the JSON format, because well, it’s cooler. Not to mention way more performant than XML as much less data is being set across the wire, and because the query.v1 endpoint allows you to execute multiple queries at one time, getting back multiple resultsets which you cannot do with the rest-1.v1/Data endpoint.

When it comes to parsing JSON data in Java, there are an absolute multitude of libraries that can be used. A great place to start is which lists many of the libraries that are available for Java and other programming languages. Perhaps the simplest one to use that I have found so far is the json-simple library found here:

Using this library, you simply instantiate the parser, passing it the JSON that you want parsed. For example, here’s a bit of code that will parse the data returned from a query sent to the query.v1 endpoint (assuming that the data returned is stored in a String called “jsonData”):

import org.json.simple.JSONArray;
import org.json.simple.parser.JSONParser;
import org.json.simple.parser.ParseException;

JSONParser parser = new JSONParser();
JSONArray resultsets = (JSONArray) parser.parse(jsonData);
JSONArray results = (JSONArray) resultsets.get(0);

for (Object result : results) {

Notice that code that first gets the resultsets, then gets the results within those resultsets. There is reason to this this madness, and that is that calls to the query.v1 endpoint returns its results as an “array of arrays”. The outer array contains the multiple resultsets that may be returned, while the inner array contains the results returned within each resultset, which is typically an array of VersionOne assets serialized as JSON objects.

Another aspect to consider when working with JSON data is that of serialization. Sometimes it can be useful to serialize JSON data into strongly typed Java objects. Again, there are many different libraries out there that you can use for this, but one that I have found quite useful is gson which you can find here:

Using gson, you can serialize JSON objects into custom Java objects, which are sometimes referred to as Data Transfer Objects (DTOs). Here’s an example:


Gson gson = new Gson();
List<Epic> epics = new ArrayList<Epic>();

for (Object result : results) {
  Epic epic = gson.fromJson(result.toString(), Epic.class);

In this example, I took the results object created from the json-simple parser, then looped through those results and serialized them into an ArrayList of custom Java objects using gson, in this case, as custom Epic objects.

Here’s what the custom Epic object looks like:


public class Epic {

  public String Oid;

  public String Name;

  public String Status;

  public String Description;

  public String toString() {
    return "Oid: " + Oid
      + "\nName: " + Name
      + "\nStatus: " + Status
      + "\nDescription: " + Description + "\n";

Notice the use of the @SerializedName annotation. This is used because many of the attribute names return from the VersionOne API contain a “.” in them. The gson parser expects that the field names in your DTOs exactly match the JSON names, but Java does not allow the “.” in field names.

In the next article, I’ll talk about a key aspect of building an integration that makes use of APIs, and that is using a HTTP Client. The HTTP Client is the library that you will use to make the HTTP requests to the API, and then handle the HTTP responses that are returned.

Join the Discussion

    There are currently no comments.

    − 1 = 1