REST API: looking for clarification on default query limit behavior

    I'd like to gain clarity on default query limit behavior. For example, I'm currently playing with the `GET /api/v1/servers` endpoint.

    The OpenAPI spec defines a `limit` query param with minimum: 0, but doesn't specify a default value. I only have a few servers, so:

    • What happens when `limit` is not provided? Does the API return all servers, or is there a server-side default that should be documented?
    • Is there a maximum allowed value for limit?
    • How do we ensure pagination is idempotent? It may be possible after a limit(+offset) that the query results can change, resulting in missed servers on the next page limit+offset(+offset).

    It would be helpful if these defaults/limits could be documented in the OpenAPI spec (via default and maximum in the schema).

    Einmal editiert, zuletzt von leee (29. November 2025 um 22:29)

    Hello leee

    first of all, very sorry for the delayed response – the time before Christmas is always quite busy!

    Nevertheless, we still owe you some answers.  :saint:

    • What happens when `limit` is not provided? Does the API return all servers, or is there a server-side default that should be documented?
      When "limit" is not provided, the results are not limited on server-side. You are going to get all your data.
    • Is there a maximum allowed value for limit?
      Currently not. We will introduce a limit soon and document it in the OpenAPI spec.
    • How do we ensure pagination is idempotent? It may be possible after a limit(+offset) that the query results can change, resulting in missed servers on the next page limit+offset(+offset).
      The result is ordered by server name, so that pagination is idempotent.
      If you order a new server in the meantime, the query is not idempotent.

    We hope this is helpful – and as always: thank you very much! :)

    Kind regards
    Sarah & the netcup team


    One more follow-up about this that I forgot to ask:

    After server-side implements a default limit, if we request using limit=0 for example will we be able to retrieve all items at once?

    You as well, have a great weekend and happy holidays! 🦆

    Hello leee

    in regards to your follow-up question:
    If limit=0 is set, an empty list is returned. The use case for this is to obtain the total count without loading any data. To retrieve all data, limit=null can be set. The missing OpenAPI spec with nullable=true will be added soon.

    As always: Thank you! :)

    Wishing you a merry Christmas,
    Sarah & the netcup team