Hey guys, I think we shouldn't change the existing APIs this way since - as Adam said as well - it's going to be a breaking change.
Let's do a versioned upgrade of the API just like I did for the Clients API (v2): https://github.com/apache/fineract/blob/7cb63225214f18e5e8f32b202b0ead7be1f074d0/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/api/v2/search/ClientSearchV2ApiResource.java That way clients can choose which API to use instead of breaking them. Note: later on we can remove the old, non-paginated API but let's not be hasty breaking stuff. Best, Arnold Arnold Gálovics *CEO, Co-Founder* *+36 30 904 1885* https://docktape.com Docktape Technologies On Wed, Aug 5, 2026 at 4:34 PM Ádám Sághy <[email protected]> wrote: > Hi, > > > Thanks for bringing this up! > > > This behavior is *unfortunate* and *problematic*. > > > My recommendation is to: > > - Eliminate the “paged” or “not paged” behavior and enforce all APIs to > return multiple items as a *paged* *list* by default. > > - Rework APIs that return two different data types based on parameters to > use only one data type. For example, `GET /v1/audits` should return a *paged > list of audit items.* > > > We must clearly announce the change since it breaks things, but I believe > it’s for the greater good! > > > Regards, > > Adam Saghy > > > > On Aug 4, 2026, at 8:27 AM, elnafateh <[email protected]> wrote: > > Hi all, > > While adding typed OpenAPI responses for GET /v1/audits (FINERACT-2165), > a reviewer flagged that the schema I'd added was inaccurate: the endpoint > returns a plain JSON array when paged is false or omitted, and a > {totalFilteredRecords, > pageItems} wrapper when paged=true. A single @ApiResponse schema can only > describe one of those shapes, so whichever one we document, the spec > misrepresents the other. > > This isn't unique to Audits. GroupsApiResource, CentersApiResource, and > FixedDepositAccountsApiResource all have the identical pattern — a > boolean paged param that silently switches the response between a raw > array and a page wrapper — and all three currently document only the > wrapper shape, meaning their generated clients are already inaccurate for > unpaged calls. This looks like it was a deliberate design choice at some > point (likely to preserve backward compatibility for older non-paginated > consumers), but it's now actively blocking correct typed-client generation > for any of these five resources. > > For contrast, ClientsApiResource, LoansApiResource, and > SavingsAccountsApiResource don't have this problem at all — they support > offset/limit but always return the single, unambiguous page-wrapper > shape, with no boolean toggle to a raw array. That's arguably how this > should have been designed everywhere from the start. > > I'd like the list's input on how to resolve this, since it affects > multiple resources and the fix scope depends on how much we're willing to > change. > > Happy to pick this up once there's consensus, and to apply whatever we > land on consistently across all affected resources. > > Thanks, Lukman > > >
