ExpressAPI - Run-time Operators - Display Parameter

The APIs, by their very nature, are essentially the bridge between two or more interconnected systems. These systems facilitate their business processes, and they utilise the APIs to interconnect and exchange data for allowing an extended business process to be realised across multiple systems.

Any technology or solution, and in our case, the APIs, are susceptible to run time issues. When we run into runtime issues for APIs, it's generally a very cumbersome task to assess the root cause. The root cause could be related to any touch points within the entire data exchange lifecycle. The issue could be within the source system, related to the transmission of the data, or something at the receiving system. There could be security, authentication, network-related connectivity, and transmission issues.

There are other scenarios where a particular data exchange between two systems could fail. This could be related to the different level of validations APIs has to perform before the data can be committed to the underlying core objects.

Other areas of concern are the performance of the APIs. As API administrators and owners, we need to get a grip on the performance and be able to proactively check for bottlenecks.

While conducting root cause analysis, it is essential to be able to look under the hood. Generally, Administrators will look at multiple log files and sometimes have to invest multiple hours before a root cause for failure can be determined.

While looking for a solution to these issues, flexibility and quick turnaround for these assessments were on top of our minds.

Display Parameter (represented by "d"):

We created a "Display Parameter" option to allow users to control the overall governance of the API elements. The users can choose to include or exclude certain core elements of the API response.

The Display Parameter consists of the following Operators:

• Data Operator - allows viewing the response element where the business data is included. The "data" element is displayed by default; however, it is not mandatory to retrieve the data element.

• Stats Operator - allows viewing the performance statistics for the API. The "stats" operator exposes runtime performance timings in milliseconds.

• Counts Operator - allows viewing only the counts of the records. The "counts" operator can be combined with another display operator to get the desired results. The count operator can be used independently if only the count is required sans any data.

• Debug Operator - allows viewing the complete internal information on API processing. Users can only utilise the "debug" operator if they are part of the TRIRIGA "Admin" group. Furthermore, this operator is only to be used for temporary root cause analysis scenarios where there are any issues with the data exchange. The debug operator will document the processing steps in detail and identify any specific issues early in the troubleshooting phase.

The data and counts elements are displayed as a default; however, the behaviour can be adjusted based on the requirements using the display parameter.

Fig 1: Display Parameter

For further technical information, please click on the arrows below to expand the required list:

How do these operators work?

All operators become part of the query string in a pre-defined structure. The display parameter has a JSON syntax; however, it's much simpler and straightforward. Let’s take a use case: A user would like to get the data and the count of the records. The display parameter (represented by “d”) will be like this: d={["counts", "data"]}

It is also the default behaviour of the API platform to respond with "data" and the "counts" elements, so the d operator need not be included in this case. Similarly, if we want to check the API performance, we can structure the parameter like this: d={["counts", "data", "stats"]}

Data Operator:

The response data is attached to the "data" element in the JSON payload. Although the data element is included in the payload by default, the "data" operator can skip the data element while performing other operations like checking only for counts.

Stats Operator:

The "stats" operator is quite helpful in assessing performance bottlenecks. The operator will provide essential insights into the processing steps, and the response can be used to fine-tune any specific areas of concern.

Fig 2: Statistics Operator

The "stats" operator exposes runtime performance timings in milliseconds.

Counts Operator:

The "counts" operator is generally included by default, however, in scenarios where we only want the counts to be displayed, we can skip the other display operators to achieve the desired results.

Fig 3: Counts Operator

Debug Operator:

The "debug" operator is included in the run-time to simplify troubleshooting. Generally, an Admin has to look at multiple touchpoints to assess the source of errors.

Fig 4: Debug Operator

Not having a view of the run-time execution presents many challenges and requires log file assessment from multiple places to get to any conclusion. The debug operator will enable the debug element in the response, which includes a trace of internal processing. Admin can immediately assess if there were any failures in the API execution. This operator is only enabled for the Users who are part of the TRIRIGA Admin group. For others, this operator will just be ignored.

The debug operator creates additional processing demand; thus, it needs to be used only when required for troubleshooting and short periods.

This post is part of a series detailing the ExpressAPI Features and Capabilities.

If you need to discuss anything, don't hesitate to contact us through this link.

Please read our Privacy policy here.