III-6939 Improve SAPI3 pagination feature tests

docs/architecture.md

@@ -78,6 +78,10 @@ SAPI3 is an external search service (Elasticsearch-based) that:
 - `/organizers` - Search organizers
 - `/offers` - Search events and places combined
 
+## Request Processing
+
+All API requests inside udb3-backend are processed synchronously, except for the export call. This means after creating or updating an entity, no waiting is needed before making subsequent requests to the same entity.
+
 ## Docker Services
 
 | Service | Port | Purpose |

docs/features/search.md

@@ -12,6 +12,7 @@ Acceptance tests for the SAPI3 (Search API 3) integration.
 ## Test Files
 
 - `auth.feature` - Authentication tests
+- `pagination.feature` - Pagination and sorting tests
 - `search-proxy.feature` - Search endpoint proxy tests
 - `facets.feature` - Facet response tests
 - `contributors.feature` - Contributor filtering
@@ -22,3 +23,21 @@ Acceptance tests for the SAPI3 (Search API 3) integration.
 1. Create entity (event/place/organizer) via API
 2. Poll SAPI3 endpoint waiting for indexing (max 5 seconds)
 3. Assert search results
+
+## Query Parameters
+
+SAPI3 supports two types of query parameters:
+
+- **URL parameters**: Direct query string parameters (e.g., `labels=my-label`)
+- **Advanced query parameter**: The `q` parameter using Lucene syntax (e.g., `q=labels:my-label`)
+
+## Test Isolation
+
+Search tests can use scenario-based label isolation to prevent interference from other tests:
+
+- Tag scenarios with `@labelIsolation` to enable isolation
+- A unique label (`scenario-{uuid}`) is automatically generated per scenario
+- The label is added to all fixtures created during the scenario
+- Search queries automatically filter by this label
+
+This ensures each scenario only sees its own data, regardless of what other tests create.

features/search/pagination.feature

@@ -0,0 +1,98 @@
+@sapi3
+Feature: Test the Search API v3 pagination and sorting
+
+  Background:
+    Given I am using the Search API v3 base URL
+    And I am using a x-client-id header for client "test_client_sapi3_only"
+    And I send and accept "application/json"
+
+  Scenario: Default itemsPerPage should be 30
+    When I send a GET request to "/offers"
+    Then the response status should be "200"
+    And the JSON response at "itemsPerPage" should be 30
+
+  Scenario: Custom limit is accepted
+    When I send a GET request to "/offers" with parameters:
+      | limit | 50 |
+    Then the response status should be "200"
+    And the JSON response at "itemsPerPage" should be 50
+
+  Scenario: Limit above 2000 returns error
+    When I send a GET request to "/offers" with parameters:
+      | limit | 3000 |
+    Then the response status should be "404"
+    And the JSON response should be:
+    """
+    {
+      "title": "Not Found",
+      "type": "https:\/\/api.publiq.be\/probs\/url\/not-found",
+      "status": 404,
+      "detail": "The \"limit\" parameter should be between 0 and 2000"
+    }
+    """
+
+  Scenario: Different start is possible
+    When I send a GET request to "/offers" with parameters:
+      | start | 10 |
+    Then the response status should be "200"
+
+  Scenario: Start above 10000 returns error
+    When I send a GET request to "/offers" with parameters:
+      | start | 1000000 |
+    Then the response status should be "404"
+    And the JSON response should be:
+    """
+    {
+      "title": "Not Found",
+      "type": "https:\/\/api.publiq.be\/probs\/url\/not-found",
+      "status": 404,
+      "detail": "The \"start\" parameter should be between 0 and 10000"
+    }
+    """
+
+  Scenario: Sort by availableTo ascending
+    When I send a GET request to "/offers" with parameters:
+      | sort[availableTo] | asc |
+    Then the response status should be "200"
+
+  Scenario: Sort by availableTo descending
+    When I send a GET request to "/offers" with parameters:
+      | sort[availableTo] | desc |
+    Then the response status should be "200"
+
+  Scenario: Sort by completeness ascending
+    When I send a GET request to "/offers" with parameters:
+      | sort[completeness] | asc |
+    Then the response status should be "200"
+
+  Scenario: Sort by created ascending
+    When I send a GET request to "/offers" with parameters:
+      | sort[created] | asc |
+    Then the response status should be "200"
+
+  Scenario: Sort by distance ascending
+    When I send a GET request to "/offers" with parameters:
+      | coordinates    | 50.8511740,4.3386740 |
+      | distance       | 10km                 |
+      | sort[distance] | asc                  |
+    Then the response status should be "200"
+
+  Scenario: Sort by modified ascending
+    When I send a GET request to "/offers" with parameters:
+      | sort[modified] | asc |
+    Then the response status should be "200"
+
+  Scenario: Sort by modified descending
+    When I send a GET request to "/offers" with parameters:
+      | sort[modified] | desc |
+    Then the response status should be "200"
+
+  Scenario: Sort by score ascending
+    When I send a GET request to "/offers" with parameters:
+      | sort[score] | asc |
+    Then the response status should be "200"
+
+  Scenario: Sort by score descending
+    When I send a GET request to "/offers" with parameters:
+      | sort[score] | desc |
+    Then the response status should be "200"