The current options to handle the REST API response data are cumbersome. Most of the time, the API Consumer receives a large set of unwanted data, mainly in a format that requires further handling before the target system or App can consume the data.
There is generally no option to only fetch the specific fields required for the consuming system. The consumer downloads all the fields from the data model and has to parse the response data to extract the required fields. This becomes a high-impact issue with extensive data set as it increases the consumer system's response time.
Having to download a large set of data records is also a common issue faced by API consumers. There is generally no control on limiting the number of records to download.
In other complex scenarios, a Consumer looking to have data for any child or linked records will have to execute multiple API calls and combine the data to achieve the target payload before it can be consumed. This introduces a complex API consumption pattern and adds to the development timelines.
Additionally, in scenarios where the Consumer system needs to download the media like documents, images, etc., a separate API call is required to fetch each media record for a parent record. This again creates a complex API consumption pattern and degrades the performance considerably for the Consumer system.
These issues and gaps were on top of our minds while looking at ways to control the response output and only fetch the required data in the required format.
Hint Parameter (represented by "h"):
We created a "Hint Parameter" option to allow the Consumer to control the handling of the response data.
The Hint Parameter consists of the following Operators:
Data Control Operator - allows tighter control on handling the data. For example, "Sort" can be used to sort the data with one or more fields; "Max" can be used to limit the no of records being returned; "Fields" can be used to select only specific fields to be returned; "Page" allows to paginate between the set of records.
Child & Linked Data Operator - allows pre-fetching of a child or linked records from within the parent record. For example, "Children" can fetch records from hierarchy objects. A use case could be to pre-fetch all the floors for a Building record. Similarly, "Linked" can fetch records from linked objects. A use case could be to pre-fetch linked records like documents, comments, images, etc.
Media Operator - allows pre-fetching of the content of particular pre-defined linked objects. For example, "Media" can be used to download the content for documents or images along with the parent record. As a default behaviour, only metadata is included in the payload for the media fields like documents, images, etc. This operator can help skip multiple costly calls to the backend APIs.
Fig 1: Hint Parameter
For further technical information, please click on the arrows below to expand the required list:
How do these operators work?
Data Control Operators:
Child & Linked Data Operators:
Media Operator:
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.
Comments