Merge pull request #8322 from camunda/nicpuppa/client-breaking-change-pagination

docs(api): address breaking changes the java client

Author: nicpuppa

docs/apis-tools/migration-manuals/migrate-to-89.md

@@ -68,8 +68,8 @@ Review the actions required for the following 8.9 changes:
 | <span className="label-highlight red">Breaking change</span> | [Resource deletion endpoint now returns a response body](#resource-deletion)                                        |
 | <span className="label-highlight red">Breaking change</span> | [Search filter validation errors now return structured error collections](#search-filter-validation-errors)         |
 | <span className="label-highlight red">Breaking change</span> | [Spring Boot 4.0 default for Camunda Spring Boot Starter](#spring-boot)                                             |
+| <span className="label-highlight red">Breaking change</span> | [Type-safe pagination model in the Camunda Java client](#type-safe-pagination)                                      |
 | <span className="label-highlight red">Breaking change</span> | [`versionTag` returns `null` instead of empty string when absent](#version-tag-null)                                |
-| <span className="label-highlight red">Breaking change</span> | [Web Modeler changes](#web-modeler)                                                                                 |
 | <span className="label-highlight yellow">Deprecated</span>   | [Deprecated: enum literals in Orchestration Cluster API v2](#deprecated-enum)                                       |
 
 ## Breaking changes
@@ -431,6 +431,48 @@ If your code parses error response bodies from search endpoints for specific val
 - The `detail` field now contains more descriptive, structured messages.
 - A collection of validation errors in the response body (instead of a single error message).
 
+### Type-safe pagination model in the Camunda Java client {#type-safe-pagination}
+
+#### Change
+
+The Camunda Java client now uses type-safe pagination interfaces (`AnyPage`, `OffsetPage`, `CursorForwardPage`, `CursorBackwardPage`) instead of the previous `SearchRequestPage` class. Each search or statistics endpoint exposes only the pagination methods it actually supports.
+
+Direction methods on `AnyPage` now return style-specific interfaces: `from()` returns `OffsetPage`, `after()` returns `CursorForwardPage`, and `before()` returns `CursorBackwardPage`. This prevents mixing incompatible pagination styles at compile time.
+
+#### Why
+
+The previous API allowed mixing incompatible pagination styles (for example, `.page(p -> p.from(10).after("cursor"))`), which always resulted in a `400 Bad Request` at runtime. This change surfaces that restriction at compile time. The pattern mirrors the existing sort polymorphism design (`TypedSortableRequest`).
+
+#### Impact
+
+This change is **not binary-compatible**. Code compiled against the previous API will fail at runtime without recompilation, because the method signature changed from `page(Consumer<SearchRequestPage>)` to `page(Consumer<AnyPage>)`. All users must recompile their applications.
+
+Additionally, `TypedSearchRequest` now has 4 generic type parameters (previously 3) and `TypedPageableRequest` now has 2 (previously 1), which is a source-breaking change for custom implementations of these interfaces.
+
+#### Migration reference
+
+| Before (8.8)                                       | After (8.9)                                                 |
+| :------------------------------------------------- | :---------------------------------------------------------- |
+| `import ...search.request.SearchRequestPage`       | `import ...search.page.AnyPage`                             |
+| `import ...search.request.SearchRequestOffsetPage` | `import ...search.page.OffsetPage`                          |
+| `Consumer<SearchRequestPage>`                      | `Consumer<AnyPage>`                                         |
+| `Consumer<SearchRequestOffsetPage>`                | `Consumer<OffsetPage>`                                      |
+| `SearchRequestBuilders.searchRequestPage(fn)`      | `SearchRequestBuilders.anyPage(fn)` (old method deprecated) |
+| `implements TypedSearchRequest<F, S, Self>`        | `implements TypedSearchRequest<F, S, AnyPage, Self>`        |
+| `implements TypedPageableRequest<Self>`            | `implements TypedPageableRequest<AnyPage, Self>`            |
+| `SearchRequestPage r = p.from(10)`                 | `OffsetPage r = p.from(10)`                                 |
+| `SearchRequestPage r = p.after("c")`               | `CursorForwardPage r = p.after("c")`                        |
+
+#### Action
+
+Update to the latest Java client version and **recompile your application**. If you use inline lambdas with valid pagination patterns (for example, `.page(p -> p.from(5).limit(10))`), your source code does not require changes — but recompilation is mandatory.
+
+If you have explicit references to `SearchRequestPage`, replace them with `AnyPage`. If you store the return value of direction methods (for example, `SearchRequestPage r = p.from(10)`), update the variable type to `OffsetPage`, `CursorForwardPage`, or `CursorBackwardPage` as appropriate.
+
+:::note
+This change is specific to the Camunda Java client. Generated clients and custom REST API integrations are not affected.
+:::
+
 ## Deprecations
 
 Review the actions required for the following deprecations:

docs/reference/announcements-release-notes/890/890-announcements.md

@@ -359,6 +359,36 @@ Previously, only the first conversion error was returned. This fix improves cons
 </div>
 <div className="release-announcement-content">
 
+#### Type-safe pagination model in the Camunda Java client
+
+Starting with 8.9.0, the Camunda Java client uses type-safe pagination interfaces (`AnyPage`, `OffsetPage`, `CursorForwardPage`, `CursorBackwardPage`) instead of the previous `SearchRequestPage` class. Each search or statistics endpoint now exposes only the pagination methods it actually supports.
+
+Previously, the API allowed mixing incompatible pagination styles (for example, `.page(p -> p.from(10).after("cursor"))`), which always resulted in a `400 Bad Request` at runtime. This change surfaces that restriction at compile time.
+
+This change is **not binary-compatible**. Code compiled against the old API will fail at runtime without recompilation, because the method signature changed from `page(Consumer<SearchRequestPage>)` to `page(Consumer<AnyPage>)`. All users must recompile, even if their source code does not require changes.
+
+**Action:** Take the following action for your integration type:
+
+| Integration type                                                                   | Action required                                                                                                   |
+| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
+| Lambda-based pagination (for example, `.page(p -> p.from(5).limit(10))`)           | Recompile your application. Source code changes are not required for valid pagination patterns.                   |
+| Explicit `SearchRequestPage` references                                            | Replace with `AnyPage` (import `io.camunda.client.api.search.page.AnyPage`).                                      |
+| Explicit `SearchRequestOffsetPage` references                                      | Replace with `OffsetPage`.                                                                                        |
+| Custom `TypedSearchRequest` implementations                                        | Add a pagination type parameter (3 → 4 generic params).                                                           |
+| Custom `TypedPageableRequest` implementations                                      | Add a pagination type parameter (1 → 2 generic params).                                                           |
+| Storing direction method returns (for example, `SearchRequestPage r = p.from(10)`) | Use `OffsetPage r = p.from(10)`, `CursorForwardPage r = p.after("c")`, or `CursorBackwardPage r = p.before("c")`. |
+
+<p className="link-arrow">[8.9 API migration guide](../../../apis-tools/migration-manuals/migrate-to-89.md#type-safe-pagination)</p>
+
+</div>
+</div>
+
+<div className="release-announcement-row">
+<div className="release-announcement-badge">
+<span className="badge badge--breaking-change">Breaking change</span>
+</div>
+<div className="release-announcement-content">
+
 #### `versionTag` now returns `null` instead of empty string when absent
 
 Starting with 8.9.0, API response fields for `versionTag` return `null` instead of an empty string `""` when no version tag is set. This properly indicates absence rather than leaking an internal default.