Changed 4.1 Pagination and Headers

[rartych]

What type of PR is this?

• documentation

What this PR does / why we need it:

This PR updates the CAMARA API Design Guide with comprehensive pagination guidelines. The changes modernize and restructure the pagination section to provide clearer specifications for API implementations. Key updates include:

• Simplified and more explicit pagination query parameters (page and perPage) with clear default values and constraints
• Addition of structured response body schema with ResourceList and Pagination objects
• Documentation of optional pagination response headers (X-Total-Count, X-Total-Pages, and RFC 8288 Link headers)
• Clarified HTTP status codes for pagination scenarios (200 for all valid responses including empty results and out-of-range pages, 400 for malformed input) — This is a design choice that can be changed here or 200 can be extended with context information
• Removal of the deprecated seek parameter and Content-Last-Key header

These changes provide API developers with clearer, more standardized pagination implementation guidance aligned with common REST API best practices.

Which issue(s) this PR fixes:

Fixes camaraproject#592

Does this PR introduce a breaking change?

• Yes
• No
  Up to Fall25 pagination was used only in one API (CarrierBilling)

Special notes for reviewers:

• The removal of the seek parameter and Content-Last-Key header represents a simplification of the pagination specification rather than a breaking change to the design guide itself
• The current Guide uses page=0 for the first page. The PR switches to 1-indexed (default: 1, minimum: 1) — both approaches are common in REST APIs, the proposal may be changed here
• The new pagination structure is more explicit about error handling and edge cases (empty results, out-of-range pages)
• Additional schema examples and HTTP header documentation support clearer API implementation across CAMARA services

Changelog input