Unexpected API Pagination Behavior: A Silent Challenge for Software Project Planning

In the intricate world of API consumption, subtle undocumented behaviors can lead to significant headaches for developers. A recent discussion on the GitHub Community forums brought to light one such nuance concerning the GitHub Actions API, specifically around how it handles invalid per_page values in pagination requests. This insight is crucial for robust software project planning and ensuring predictable API interactions.

The Silent Default: When Invalid Pagination Parameters Go Unnoticed

The discussion, initiated by ramzanbhutto, highlighted an unexpected behavior when querying the GET /repos/{owner}/{repo}/actions/runs endpoint. Developers passing per_page=0 or negative values like per_page=-1 might reasonably expect an error (e.g., a 400 Bad Request) or perhaps an empty result set. However, the GitHub API silently ignores these invalid inputs, returning 30 workflow runs with a 200 OK status, which is the default page size.

Consider these example API calls:

• https://api.github.com/repos/microsoft/vscode/actions/runs?status=failure&per_page=0
• https://api.github.com/repos/microsoft/vscode/actions/runs?status=failure&per_page=-1

Both URLs, despite their seemingly invalid per_page parameters, consistently yield 30 results. This behavior, confirmed across multiple repositories, poses a significant risk. A client application expecting an error or no data for a per_page=0 request could silently receive actual data, leading to hard-to-detect bugs and flawed data processing logic within a larger software project planning context.

Community Clarification: Clamping, Not Rejecting

Fellow community member tahleho3968 provided valuable clarification, confirming that this isn't an isolated bug in the Actions API but rather a GitHub-wide REST API pagination behavior. Instead of rejecting out-of-range values with an error, the API "clamps" them. This means:

• Values less than or equal to 0 default to 30.
• Values greater than the maximum (typically 100) are capped at 100.

This "clamping" behavior, while a common API design choice to prevent server errors on edge cases, is problematic when undocumented for the lower bound. The official REST pagination documentation only explicitly mentions the upper bound ("results per page (max 100)"), leaving developers to discover the lower-bound default through trial and error or community discussions.

Practical Takeaways for Robust API Integration

Given this undocumented behavior, developers integrating with GitHub's REST API should adopt proactive strategies to safeguard their applications and improve developer productivity:

• Client-Side Validation: Always validate and clamp per_page values on the client side to a sensible range (e.g., 1 to 100) before sending the request. This ensures your application's intent is respected.
• Authoritative Response: Treat the actual item count in the API response as authoritative. If you requested 0 results and received 30, that's a clear signal that your parameter wasn't honored as expected.
• Documentation Improvement: As suggested in the discussion, a simple note in the official documentation stating, "values ≤ 0 fall back to default (30)," would significantly reduce confusion and prevent potential bugs.
• Consider 422 for Out-of-Range: While clamping is a design choice, a more explicit signal like a 422 Unprocessable Entity error for out-of-range per_page values could offer clearer feedback to API consumers, aligning with best practices for robust API design.

Understanding these subtle API behaviors is vital for effective software project planning and building resilient applications. This community insight underscores the importance of clear API contracts and comprehensive documentation to avoid unexpected outcomes and ensure smooth development workflows.