All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading