Handling HTTP Responses

If you are new to web service interfaces, first review HTTP Response Structure for an overview of what information you can typically find in an HTTP response.

We’ve covered how Building HTTP Requests. Now let’s take the resulting response from our request and break down strategies for handling HTTP responses.

The way you handle HTTP responses will depend on the API your working with and your interface requirements, however there are fundamental concepts to help you build your logic to handle your unique responses. Here is a simple example:

retry.call from the Retry Library returns a success parameter, which you can use as the start of your framework to check if the HTTP request was successful.

Using if statements you can apply conditional logic, depending on the success value, and branch your handling accordingly.

Depending on the data type and format of the response, you can capture additional information, such as the data you fetched, success or error messages.

Typically a response will either be in JSON or XML format:

For JSON: json.parse{}
For XML: xml.parse{}

HTTP status codes provide valuable information about the outcome of the request, and based on these codes, different actions can be taken, such as further retries or error handling.

Here we are using Arithmetic Operators to capture all possible 2XX status codes.

If a 2XX code is returned, we are treating it as a success and returning the response message. This is typically when you would queue or perform any additional processing on the data.
If a code outside of the 2XX series is returned, we are logging an error. This stage is when you have the flexibility to handle the outcome as required - whether that means logging an error to trigger a notification for your team or retrying the original request.

This is a simple example for response handling. You may not want to handle every http status code the same way. In production, you can create your own conditional logic based on your requirements and use the HTTP status codes to guide you:

local retryCodes = {
  [404] = true, -- Not Found: the resource was not found but may be available in the future
  [408] = true, -- Request Timeout: the server timed out probably temporarily overloaded
  [503] = true, -- Service Unavailable: temporaily unavailable or overloaded
  [429] = true  -- Too Many Requests: too many requests or concurrent connections 
}

local funcSuccess 
-- Parse results and apply simple error, handling according to the API responses
if success then
  local R = json.parse{data=response}

   -- Check HTTP codes
   if code >= 200 and code <300 then
      iguana.logMessage(response)
      funcSuccess = true -- don't retry
      return R, code -- return response for further processing

    -- if retryCode returned, funcSuccess = false to retry function call 
    elseif retryCodes[code] then 
      iguana.logInfo('Web service connection error: '..tostring(code)..' - '..tostring(errMsg))        
      funcSuccess = false -- retry

    -- in this case we don't want to retry, instead invoke token refresh workflow or check credentials
    elseif code == 401 then 
       iguana.logInfo('Web service connection error: '..tostring(code)..' - refreshing token')
       getToken() -- trigger workflow to refresh token
       funcSuccess = true -- don't retry
    
    -- any other code can be considered an error
    else     
       -- logError() logs an error message to skip this message and trigger notification rule 
       -- use error() to stop the component on error 
       iguana.logError('WebService connection: ERROR '..tostring(code)..' - '..tostring(errMsg))
       funcSuccess = true -- don't retry  
    end
end