Easily Convert and Parse Simple JSON Responses

In the world of APIs, there are many that are simple HTTP requests with simple responses. The request body may be small JSON, XML, or even an empty payload. Similarly, the response body may also be small JSON, XML, or other formats. In these cases, one could argue that the overhead of a Transformation component might be unnecessary and the entire HTTP exchange can be done within a Script. (Also perfect for retry loops on those less-reliable APIs)

With this transformation-less goal, we can make three points for non-archive, transformation-less operations
1. Read/WriteFile() functions can reference HTTP endpoints, which can put results in Jitterbit Targets or variables,
2. XML functions and Jitterbit JSON tricks (see below) can extract results and
3. Standard API calls like token or session ID acquisitions almost always fall into a utility nature.

Utility operations detract from the visual representation of a data pipeline. With that said, it’s wise to make them sensitive to errors and very verbose when errors occur.

In this post, we’ll show an approach for a transformation-less operation. The example gets the Jitterbit authentication token for using Jitterbit’s API. Worth noting, this technique is useful for renewing or refreshing API authentication tokens and session IDs. This allows the data pipeline to continue without halting. In those cases, I stored expiring tokens or IDs as cloud variables.

We begin top-down with the utility script called to collect the authentication token.

// For collecting a current, valid Harmony authentication token
If!IsValid(
  $harmony.authenticationToken = RunScript("<TAG>Scripts/Harmony API/Request Harmony token</TAG>",
      $HARMONY.credentials.email,$HARMONY.credentials.password)
  ),
    RaiseError("Token Request FAILED\r\n"+GetLastError());
);
RunScript("<TAG>Scripts/Handlers/Event</TAG>",6,"Harmony Auth Token",$harmony.authenticationToken);

Harmony API/Request Harmony token

IfEmpty($HARMONY.http.host, 
  SetLastError('Please set (Project) variable HARMONY.http.host'); RaiseError(GetLastError())
);
email = IfEmpty(_1,
  SetLastError('Please set (Project) variable HARMONY.credentials.email'); RaiseError(GetLastError())
);
password = IfEmpty(_2,
  SetLastError('Please set (Project) variable HARMONY.credentials.password'); RaiseError(GetLastError())
);
$harmony.respFilebaseName = 
  RunScript("<TAG>Scripts/Utilities/NameGen</TAG>","HMauthResponse"); 
RunScript("<TAG>Scripts/Handlers/Event</TAG>",6,"Harmony Response File",
  $harmony.respFilebaseName+".json"
);
// PUT simple JSON to [HARMONY.http.host]/user/login
WriteFile("<TAG>Targets/Harmony/PUT /user/login</TAG>",
  '{ "email": '+DQuote(email)+', "password": '+DQuote(password)+' }'
  );
FlushFile("<TAG>Targets/Harmony/PUT /user/login</TAG>");
// log the content of the Response
RunScript("<TAG>Scripts/Handlers/Event</TAG>",7,"Harmony token response",
  ReadFile("<TAG>Sources/Harmony/Harmony Auth Response</TAG>")
);
If(IsValid(token=RunScript("<TAG>Scripts/Abstractions/Stringified to Struct</TAG>",
    ReadFile("<TAG>Sources/Harmony/Harmony Auth Response</TAG>"),'authenticationToken'
  )),
  token
,
  RaiseError(GetLastError())
);

Abstractions/Stringified to Struct

//Replace() per JB defect and Mike's comment below
$_jbJSON = Replace(IfEmpty(_1, $jitterbit.api.request.body),":null",":\"NULL\"");
key = _2;
// Call JS to return $valuesByKey or, if applicable, $JS_err
RunScript("<TAG>Scripts/Abstractions/js:Stringified to JB Struct</TAG>");
If(Length($JS_err)>0, 
  SetLastError($JS_err); RaiseError(GetLastError());
,
  If(Length(key)>0,
    $valuesByKey[key];
  ,
    $valuesByKey;
  );
)

Abstractions/js:Stringified to JB Struct

try {
  //Important, see Mike's comment below
  var $valuesByKey= JSON.parse($_jbJSON); 
}
catch(err) {
  var $JS_err=err.message;
}

Note how the JavaScript js:Stringified to JB Struct can parse JSON and return a Jitterbit Dictionary. This JS trick is very handy for acquiring level one values from a JSON response.

The XML function SelectSingleNode() can parse and extract from an XML response. We’ll save our tips on its use for another post as this function works for complex XML responses.