# Add Pagination to a Quarkus REST API

Yes. An agent adds page and size parameters to your Panache list endpoints with a total count, bounds-checked input and REST Assured tests, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pagination/quarkus/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the list endpoints query before it changes their shape. In a service shaped like the `hibernate-orm-panache-quickstart` in quarkusio/quarkus-quickstarts, `pom.xml` imports `quarkus-bom` 3.40.1.1 with `quarkus-hibernate-orm-panache`, `quarkus-rest-jackson` and `quarkus-jdbc-postgresql`, with `quarkus-junit` and `rest-assured` for tests and Java 17 as the compiler release. `application.properties` sets a datasource URL, user and password only under `%prod`, so dev and test rely on Quarkus Dev Services to start a PostgreSQL container, and `import.sql` seeds three fruits into each of two tables. Two resources show the two Panache styles: `FruitEntityResource` at `entity/fruits` calls `FruitEntity.listAll(Sort.by("name"))` on an entity that extends `PanacheEntity`, and `FruitRepositoryResource` at `repository/fruits` calls `fruitRepository.listAll(Sort.by("name"))` on a `PanacheRepository<Fruit>`. Both `GET` methods return the whole table as a `List`. `FruitsEndpointTest` is a `@QuarkusTest` that lists, deletes `/1` and lists again with REST Assured against both paths.

It adds the same two query parameters to both `GET` methods, `page` with a default of the first page and `size` with a default and a maximum read from `application.properties` as `fruits.page.default-size` and `fruits.page.max-size` through `@ConfigProperty`. A `size` above the maximum is clamped and a negative `page` or a `size` of zero answers `400` through the resources' existing `ErrorMapper`, which already turns a `WebApplicationException` into the JSON shape with `code` and `error`. The entity resource becomes `FruitEntity.findAll(Sort.by("name")).page(Page.of(page, size)).list()` and the repository resource the same call on `fruitRepository`, so the ordering the endpoints had is kept and the database does the limiting with `LIMIT` and `OFFSET` rather than Java slicing a full list.

The response keeps its body as a JSON array so existing clients and the Angular front end under `META-INF/resources` keep working, and carries the paging facts in headers: `X-Total-Count` from `count()`, `X-Page`, `X-Page-Size`, and a `Link` header with `next`, `prev`, `first` and `last` relations built from `UriInfo`, the convention the GitHub API uses and most clients parse. The count query runs once per request alongside the page query. A `PageParams` record with a static `of(page, size, config)` factory holds the validation so both resources share it and it can be unit-tested without the container.

Tests extend `FruitsEndpointTest`'s style: a test that `GET` with `size=2` returns two names in sorted order and `X-Total-Count` of the seeded rows, a test that the second page holds the remaining fruit and no `next` relation, a test that a `size` past the maximum is clamped to it, and tests that `page=-1` and `size=0` answer `400` with the error JSON. A plain JUnit test covers `PageParams`. The agent runs `./mvnw test`, which starts the Dev Services PostgreSQL container for the test profile, and `./mvnw package` to confirm the build, and pastes the results into the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add pagination to the list endpoints of this Quarkus service and open a pull request. Read pom.xml, src/main/resources/application.properties, src/main/resources/import.sql, both resource classes, FruitEntity.java, Fruit.java, FruitRepository.java and src/test/java/org/acme/hibernate/orm/panache/FruitsEndpointTest.java first. Add page and size query parameters to the GET list methods of FruitEntityResource and FruitRepositoryResource with a default and maximum size read from application.properties, clamp size to the maximum, answer 400 through the existing ErrorMapper for a negative page or a zero size, and query with Panache findAll(Sort.by(\"name\")).page(Page.of(page, size)).list() so the database limits the rows. Keep the body a JSON array and add X-Total-Count from count(), X-Page, X-Page-Size and a Link header with next, prev, first and last built from UriInfo. Put the parameter validation in a PageParams record shared by both resources. Write REST Assured tests for both paths covering a first page in sorted order with the total, the last page without a next link, clamping and both 400 cases, and a JUnit test for PageParams. Run ./mvnw test and ./mvnw package and paste the results in the pull request. Do not change the create, update or delete endpoints.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that edits the two resource classes' `GET` methods, adds `PageParams`, adds two properties to `application.properties`, extends `FruitsEndpointTest` and adds a `PageParamsTest`. The entities, repository, `import.sql` and the other endpoints are untouched. The description shows a request with `page` and `size` and the headers it answers with, names the defaults, and pastes the `./mvnw test` and `./mvnw package` output including the Dev Services startup lines.

A reviewer checks the default and maximum sizes against what their clients fetch, decides whether the front end should move to paged requests, and confirms the `Link` header's base URL is right behind their proxy, since `UriInfo` reflects what Quarkus sees. Then they can apply the same `PageParams` to any other list endpoint in the service.

## Run it on every Quarkus endpoint that returns a whole table

A team with several Quarkus services sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own resources, so a service on reactive Panache gets `Uni`-returning page queries and a service that already wraps responses in an envelope gets the total inside it, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request and the test output from.

## Why run it on Rush?

A list endpoint that returns a whole table works until the table grows, and the fix touches query, validation and response shape at once. What matters is that the database does the limiting and that the edge cases answer the right status, and both are only checked by running the service against a real PostgreSQL. In a Rush sandbox the agent runs `./mvnw test` with the Dev Services container the project already relies on, so the page queries execute with `LIMIT` and `OFFSET` against the seeded rows, and keeps every command and its output in the run's record for the reviewer.

The change uses Panache's own `page` and `count` on the queries the resources already make and the `ErrorMapper` they already have, so nothing is added to `pom.xml` and the two styles the quickstart demonstrates stay parallel. The same request works on any Quarkus service with Panache list endpoints.

## Frequently asked questions

### Why headers instead of a JSON envelope?

The endpoints return a JSON array today and the bundled front end reads it. Headers add the total and the links without breaking that. An envelope with `items` and `total` is a fine alternative when every client is yours, and the pull request shows where the `Response` is built if you prefer it.

### Does the database do the limiting?

Yes. `findAll(...).page(Page.of(page, size)).list()` makes Panache add `LIMIT` and `OFFSET` to the query, and `count()` runs a count query, so a large table is never loaded into the JVM to be sliced. The test output includes the SQL because `quarkus.hibernate-orm.log.sql` is on.

### What happens with a size of ten thousand?

It is clamped to `fruits.page.max-size` from `application.properties`, and `X-Page-Size` reports the size that was used. A negative page or a zero size is a `400` with the same JSON error shape the resources already return for a missing fruit.

### Do the tests need a running PostgreSQL?

Not one you start. `application.properties` sets the datasource only under `%prod`, so the test profile uses Quarkus Dev Services, which starts a PostgreSQL container for the run. The agent runs `./mvnw test` that way and the output shows the container starting.

## More Quarkus jobs

- [Add Prometheus Metrics to a Quarkus App](https://getrush.ai/run/add-prometheus-metrics/quarkus/)
- [Add Rate Limiting to a Quarkus REST API](https://getrush.ai/run/add-rate-limiting/quarkus/)
- [Add Request ID Logging to a Quarkus API](https://getrush.ai/run/add-request-id-logging/quarkus/)

## The same job on other stacks

- [Add Pagination to a Sequelize Express API](https://getrush.ai/run/add-pagination/sequelize/)
- [Add Pagination to a Slim 4 List Endpoint](https://getrush.ai/run/add-pagination/slim/)
- [Add Message History Pagination to a Socket.IO Chat](https://getrush.ai/run/add-pagination/socket-io/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
