Document that REST submissions endpoints support limit/offset

[matthew-white]

I was looking into whether the REST submissions endpoints support paging and wanted to share some of my findings. I found that the endpoints support the query parameters limit and offset:

https://github.com/getodk/central-backend/blob/61b1848ba169eb455477ebeb79f0ea745e6eb478/lib/model/query/submissions.js#L90-L103

I tried sending API requests to .../submissions and can see that limit and offset have an effect. However, the API docs indicate that paging isn't supported:

https://github.com/getodk/central-backend/blob/61b1848ba169eb455477ebeb79f0ea745e6eb478/docs/api.md?plain=1#L1869-L1871

I think we should document that these query parameters are supported. However, we should probably note, as we do for the OData endpoints, that paging does not greatly improve performance:

https://github.com/getodk/central-backend/blob/61b1848ba169eb455477ebeb79f0ea745e6eb478/docs/api.md?plain=1#L3243

This TODO can also be removed:

https://github.com/getodk/central-backend/blob/61b1848ba169eb455477ebeb79f0ea745e6eb478/lib/resources/submissions.js#L330-L334

Just wanted to share what I found as I looked into these query parameters!

[lognaturel]

Re: docs Isn’t it the case that the same filtering as odata is also supported?

[matthew-white]

I don't think so, actually: the submissions.csv and .csv.zip endpoints accept the $filter query parameter, but I'm pretty sure that the REST .../submissions endpoints don't.

[lognaturel]

Thanks! Sounds like you and @yanokwa already discussed that this could be helpful for folks who have legacy systems that process xml. Probably doesn’t warrant immediate action and I’ll mark this sub conversation as off topic.

[yanokwa]

paging does not greatly improve performance

How big of a lift is it to resolve this? It'd be nice to offer a carrot when we change defaults from returning all submissions.

[matthew-white]

As noted at #1614, there's also a deleted query parameter that seems to be supported in addition to limit and offset.