JSON and REST API Functions

JSON and REST functions are available throughout the Articles report script editor. They allow reports to retrieve live data from web services and APIs, parse JSON responses, and extract specific values for use in report expressions and scripts.

---

GetRESTJson

Makes an HTTP GET request to a REST API endpoint and returns the full JSON response as a string. Use this when you need to process the entire response yourself, or when you want to parse it with JSONParse for multiple value lookups.

GetRESTJson(URL: String): String

Parameter	Type	Description
URL	String	The full URL of the REST endpoint to call

// Retrieve a full JSON response and parse it
var json := GetRESTJson('https://api.example.com/orders/' + [Orders.OrderID]);

// Parse and extract multiple values from one call
var handle := JSONParse(json);
var status  := JSONGetValue(handle, 'status');
var shipped := JSONGetValue(handle, 'shippingDate');
JSONFree(handle);

Result := 'Status: ' + status + '  Shipped: ' + shipped;

---

GetRESTValue

Makes an HTTP GET request to a REST API endpoint and returns a single field value from the JSON response using dot notation. Use this when you only need one value from the response and do not need to parse the full JSON.

GetRESTValue(URL, FieldPath: String): String

Parameter	Type	Description
URL	String	The full URL of the REST endpoint to call
FieldPath	String	Dot notation path to the field (e.g. 'customer.address.city')

// Get a single field directly from a REST call
Result := GetRESTValue(
  'https://api.example.com/customers/' + [Customer.ID],
  'creditScore'
);

// Access a nested field using dot notation
Result := GetRESTValue(
  'https://api.example.com/orders/' + [Orders.OrderID],
  'shipping.address.city'
);

// Use a calculated URL with a field value
var url := 'https://api.exchangerate.host/latest?base=USD&symbols=' + [Invoice.Currency];
Result := GetRESTValue(url, 'rates.' + [Invoice.Currency]);

---

JSONArrayCount

Returns the number of elements in a JSON array at a specified path within a previously parsed JSON object. Use this to know how many times to loop when processing array data.

JSONArrayCount(Handle: Integer; ArrayPath: String): Integer

Parameter	Type	Description
Handle	Integer	A JSON handle returned by JSONParse
ArrayPath	String	Dot notation path to the array

var json   := GetRESTJson('https://api.example.com/invoice/' + [Invoice.ID]);
var handle := JSONParse(json);

// Find out how many line items the invoice has
var lineCount := JSONArrayCount(handle, 'lineItems');
Result := IntToStr(lineCount) + ' line items';

// Loop through each item
var i: Integer;
for i := 0 to lineCount - 1 do
begin
  var desc := JSONGetValue(handle, 'lineItems[' + IntToStr(i) + '].description');
  // process each item...
end;

JSONFree(handle);

---

JSONFree

Releases a parsed JSON object from memory. Always call JSONFree when you have finished working with a JSON handle to avoid memory leaks in long-running reports.

procedure JSONFree(Handle: Integer)

Parameter	Type	Description
Handle	Integer	The JSON handle to release, as returned by JSONParse

var json   := GetRESTJson('https://api.example.com/product/' + [Item.SKU]);
var handle := JSONParse(json);

Result := JSONGetValue(handle, 'description');

// Always free when done
JSONFree(handle);

---

JSONGetValue

Retrieves a single value from a previously parsed JSON object using dot notation. Array elements can be accessed using bracket notation with a zero-based index.

JSONGetValue(Handle: Integer; FieldPath: String): String

Parameter	Type	Description
Handle	Integer	A JSON handle returned by JSONParse
FieldPath	String	Dot notation path to the value. Use [n] for array elements (zero-based).

var json   := GetRESTJson('https://api.example.com/customer/' + [Customer.ID]);
var handle := JSONParse(json);

// Simple field
Result := JSONGetValue(handle, 'name');

// Nested field
Result := JSONGetValue(handle, 'address.city');

// Array element — first item (zero-based index)
Result := JSONGetValue(handle, 'contacts[0].email');

// Second item in an array
Result := JSONGetValue(handle, 'orders[1].orderDate');

JSONFree(handle);

---

JSONParse

Parses a JSON string and returns an integer handle that can be used with JSONGetValue, JSONArrayCount, and JSONFree. Parsing once and reusing the handle is more efficient than calling GetRESTValue multiple times for the same response.

JSONParse(JSONStr: String): Integer

Parameter	Type	Description
JSONStr	String	A valid JSON string to parse

// Parse once, read many values
var json   := GetRESTJson('https://api.example.com/order/' + [Orders.OrderID]);
var handle := JSONParse(json);

var customerName := JSONGetValue(handle, 'customer.name');
var orderTotal   := JSONGetValue(handle, 'total');
var shipCity     := JSONGetValue(handle, 'shipping.address.city');
var itemCount    := JSONArrayCount(handle, 'lineItems');

Result := customerName + ' — ' + FormatCurrencySafe(StrToFloat(orderTotal));

// Free when all values have been read
JSONFree(handle);

Important: Always call JSONFree after you are done with a handle. Each call to JSONParse allocates memory that must be released manually.