What & Why: As an example I will take GET /api/repayments?dueFrom=2011-01-05&dueTo=2011-06-07 when the result set has 1500 records. In this case, as per the pagination default settings only 50 records will be returned. The end user has no idea how many records do match the criteria even if the pagination with offset and limit is used. The enhancement is about adding in the response a field to hold the total of records matching the criteria. This value will be updated for each call to cover the cases when records have been added or removed.
How: Expose a new endpoint:
GET /api/repayments/search?dueFrom=2011-01-05&dueTo=2011-06-07. The extra field can't be added on the current result from the current endpoint (/api/repayments?dueFrom=2011-01-05&dueTo=2011-06-07) because it will not be backwards compatible.
Sketched response to ensure future backwards compatibility
This can be extended to any API response to support a generic response format with backwards compatibility.