Fix Next-Page-Cursor description

[HenrikHL]

User description

Fixes some wording that could be more clear

---

PR Type

Documentation

---

Description

• Clarified Next-Page-Cursor header documentation with backtick formatting

• Improved cursor parameter usage explanation for pagination

• Refined query parameter preservation requirements across API versions

• Standardized pagination behavior description across multiple endpoints

---

Diagram Walkthrough

flowchart LR
  A["Original Documentation"] -->|"Add backticks for clarity"| B["Formatted Header Names"]
  A -->|"Simplify parameter syntax"| C["Improved Parameter Examples"]
  A -->|"Clarify preservation rules"| D["Enhanced Query Parameter Guidance"]
  B --> E["Updated API Specifications"]
  C --> E
  D --> E

Loading

File Walkthrough

Relevant files

Documentation

CS_v1.0.2.yaml Clarify pagination cursor documentation                                    cs/v1/CS_v1.0.2.yaml Added backticks around Next-Page-Cursor header name for consistency Clarified cursor parameter usage from ?cursor=... to cursor=... format Changed "subsequent requests" to "a subsequent request" for accuracy Updated query parameter preservation to include original request parameters +9/-9      OVS_v3.0.2.yaml Standardize pagination documentation                                          ovs/v3/OVS_v3.0.2.yaml Added backticks around Next-Page-Cursor header name for consistency Simplified cursor parameter syntax from ?cursor=... to cursor=... Replaced complex error handling rules with simplified parameter preservation guidance Aligned pagination behavior with CS API specification +3/-3

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	✅ This PR introduces a breaking change Suggestion Impact: The commit modified the exact pagination description section, but it implemented the opposite behavior: it changed the spec back to "cursor-only" follow-up requests and added guidance to ignore/400 on additional query parameters, effectively removing the breaking-change behavior the suggestion called out. code diff: # File: ovs/v3/OVS_v3.0.2.yaml @@ -207,7 +207,7 @@ When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. - To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter along with the limit of items per page and any other query parameters used in the original request. Filter parameters may not be altered and MUST be preserved when requesting subsequent pages. + To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter. The limit of items per page and any other query parameters may not be altered, therefore it may also not be specified when requesting subsequent pages. The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. The update to the OVS v3 API specification is a breaking change, not a documentation fix. It changes pagination behavior from requiring only a cursor to mandating all original query parameters be resent. Examples: ovs/v3/OVS_v3.0.2.yaml [205-210] description: | The `Next-Page-Cursor` header contains a cursor value that points to the next page of results in a paginated API response. When an initial `GET` endpoint request includes the query parameter `limit=...` the API provider limits the number of items in the root array of the response to the specified limit. If the response would contain more items than the specified limit, the API provider includes only the first set of limit items and appends the following response header: `Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA` as query parameter along with the limit of items per page and any other query parameters used in the original request. Filter parameters may not be altered and MUST be preserved when requesting subsequent pages. Solution Walkthrough: Before: # in ovs/v3/OVS_v3.0.2.yaml description: | ... To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with only `?cursor=...` as query parameter. ... The API provider must ignore any query parameters passed along with a cursor, and should return a `400` error if any other query parameter is passed along with the `cursor`. After: # in ovs/v3/OVS_v3.0.2.yaml description: | ... To retrieve the next page, the API consumer sends a `GET` request to the endpoint URL with `cursor=...` as query parameter along with the limit of items per page and any other query parameters used in the original request. Filter parameters may not be altered and MUST be preserved when requesting subsequent pages. Suggestion importance[1-10]: 10 __ Why: The suggestion correctly identifies a critical breaking change in the OVS v3 API specification that was misclassified as a documentation fix, which could severely impact existing API clients.	High
General	Correct the invalid example cursor value Replace the invalid Base64 example for the Next-Page-Cursor with a valid one. The current example decodes to a confusing string, while the suggested one decodes to a standard offset=10&limit=10. cs/v1/CS_v1.0.2.yaml [69] -`Next-Page-Cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=fE9mZnNldHw9MTAmbGltaXQ9MTA`. +`Next-Page-Cursor=b2Zmc2V0PTEwJmxpbWl0PTEw`, a string that acts as a reference for the next page of results. The `Next-Page-Cursor` value is used in a subsequent request to retrieve the next page by passing it as a value in the `cursor`-query parameter: `cursor=b2Zmc2V0PTEwJmxpbWl0PTEw`. Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the Base64 encoded example cursor value is invalid and confusing, and provides a valid, clearer alternative, which improves the quality and correctness of the API documentation.	Low
Update