Add sorting to the Pull request by Base Head API #14832

New Issue

GiteaMirror · 2025-11-02T11:23:58-06:00

GiteaMirror commented

2025-11-02 11:23:58 -06:00

Originally created by @adsbhatial on GitHub (Aug 5, 2025).

Feature Description

Hi team,

The current version of the Get Pull Request by Base and Head API doesn't provide any sorting functionality for the pull request.
It will always return the pull request that was first created. This makes this API useless if the branch is used in multiple pull requests.

Could we please have some other parameters for this API, like the List Pull Request API
Adding sort, state, labels, and poster to this API will be really helpful

Thanks.

Screenshots

No response

Originally created by @adsbhatial on GitHub (Aug 5, 2025). ### Feature Description Hi team, The current version of the [Get Pull Request by Base and Head API](https://docs.gitea.com/api/next/#tag/repository/operation/repoGetPullRequestByBaseHead) doesn't provide any sorting functionality for the pull request. It will always return the pull request that was first created. This makes this API useless if the branch is used in multiple pull requests. Could we please have some other parameters for this API, like the [List Pull Request API](https://docs.gitea.com/api/next/#tag/repository/operation/repoListPullRequests) Adding `sort`, `state`, `labels`, and `poster` to this API will be really helpful Thanks. ### Screenshots _No response_

GiteaMirror added the topic/api type/proposal labels 2025-11-02 11:23:58 -06:00

GiteaMirror commented

2025-11-02 11:23:59 -06:00

@stawuah commented on GitHub (Oct 29, 2025):

Hi @lunny, @silverwind and @kemzeb 👋
I'd like to work on adding sorting and filtering to the GET /repos/{owner}/{repo}/pulls/{base}/{head} API as discussed in #35217.
My approach:

Add query parameters: state, sort, labels, page, limit
Change response from single PR to array of PRs (breaking change)
Maintain backward compatibility by returning 404 when no PRs found
Add comprehensive tests and update swagger docs

Question: Should this be a breaking change (array response), or there should be create new endpoint like /repos/{owner}/{repo}/pulls/search/{base}/{head}?
Looking forward to your feedback!

@stawuah commented on GitHub (Oct 29, 2025): Hi @lunny, @silverwind and @kemzeb 👋 I'd like to work on adding sorting and filtering to the GET /repos/{owner}/{repo}/pulls/{base}/{head} API as discussed in #35217. My approach: Add query parameters: state, sort, labels, page, limit Change response from single PR to array of PRs (breaking change) Maintain backward compatibility by returning 404 when no PRs found Add comprehensive tests and update swagger docs Question: Should this be a breaking change (array response), or there should be create new endpoint like /repos/{owner}/{repo}/pulls/search/{base}/{head}? Looking forward to your feedback!

GiteaMirror commented

2025-11-02 11:23:59 -06:00

@silverwind commented on GitHub (Oct 29, 2025):

Please check first what the GitHub API does in this case and if possible do the same.

@silverwind commented on GitHub (Oct 29, 2025): Please check first what the GitHub API does in this case and if possible do the same.

GiteaMirror commented

2025-11-02 11:23:59 -06:00

@stawuah commented on GitHub (Oct 29, 2025):

Confirmed.
I checked GitHub’s API, and it supports filtering and sorting via:

GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&base={branch}&state={state}&sort={created|updated}&direction={asc|desc}

It returns an array of pull requests (empty if no match).

For Gitea, I’ll align with this behavior by introducing a new endpoint (e.g.
GET /repos/{owner}/{repo}/pulls/search) that supports these query parameters (head, base, state, sort, direction, page, limit), while keeping the existing /pulls/{base}/{head} endpoint for backward compatibility.

@silverwind Could you please assign this issue to me so I can start working on the implementation?

@stawuah commented on GitHub (Oct 29, 2025): **Confirmed.** I checked GitHub’s API, and it supports filtering and sorting via: ``` GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&base={branch}&state={state}&sort={created|updated}&direction={asc|desc} ``` It returns an array of pull requests (empty if no match). For Gitea, I’ll align with this behavior by introducing a new endpoint (e.g. `GET /repos/{owner}/{repo}/pulls/search`) that supports these query parameters (`head`, `base`, `state`, `sort`, `direction`, `page`, `limit`), *while keeping the existing* `/pulls/{base}/{head}` endpoint for *backward compatibility*. @silverwind Could you please assign this issue to me so I can start working on the implementation?

GiteaMirror commented

2025-11-02 11:23:59 -06:00

@silverwind commented on GitHub (Oct 29, 2025):

Can we make it work exactly like GitHub, in a breaking change? GitHub compatibility is imho a very acceptable reason for a breaking change.

@silverwind commented on GitHub (Oct 29, 2025): Can we make it work exactly like GitHub, in a breaking change? GitHub compatibility is imho a very acceptable reason for a breaking change.

GiteaMirror commented

2025-11-02 11:23:59 -06:00

@stawuah commented on GitHub (Oct 31, 2025):

Hi @silverwind
Thanks for the feedback! I agree that GitHub compatibility is a good reason for a breaking change.
However, since this will be a breaking change, I'd like to propose the following approach:
Phased Implementation:

Phase 1 (Non-breaking): First, I'll implement a new endpoint (e.g., GET /repos/{owner}/{repo}/pulls/search ) that mimics GitHub's behavior with full filtering and sorting support. This allows us to:

Validate the implementation against all use cases
Gather feedback from the community
Ensure the solution works as expected

Phase 2 (Breaking change): Once the new endpoint is proven stable and passes all tests, we can:

Deprecate the old /pulls/{base}/{head} endpoint
Update it to match GitHub's array-based response
Provide a clear migration path for existing users

This approach minimizes risk while ensuring we deliver a robust, GitHub-compatible solution. If the implementation passes all use cases in Phase 1, we can confidently proceed with the breaking change.
Would this approach work for the team? Happy to discuss alternatives!

@stawuah commented on GitHub (Oct 31, 2025): Hi @silverwind Thanks for the feedback! I agree that GitHub compatibility is a good reason for a breaking change. However, since this will be a breaking change, I'd like to propose the following approach: Phased Implementation: **Phase 1 (Non-breaking)**: First, I'll implement a new endpoint (e.g., GET `/repos/{owner}/{repo}/pulls/search` ) that mimics GitHub's behavior with full filtering and sorting support. This allows us to: Validate the implementation against all use cases Gather feedback from the community Ensure the solution works as expected **Phase 2 (Breaking change)**: Once the new endpoint is proven stable and passes all tests, we can: Deprecate the old ` /pulls/{base}/{head} ` endpoint Update it to match GitHub's array-based response Provide a clear migration path for existing users This approach minimizes risk while ensuring we deliver a robust, GitHub-compatible solution. If the implementation passes all use cases in Phase 1, we can confidently proceed with the breaking change. Would this approach work for the team? Happy to discuss alternatives!

GiteaMirror commented

2025-11-02 11:23:59 -06:00

@silverwind commented on GitHub (Oct 31, 2025):

A noble approach, but realistically I think phase 2 may be forgotten and we may become stuck in phase 1. I think it's better to do it all at once, label the pull as breaking and then it will be included in the breaking changes for 1.26.

@silverwind commented on GitHub (Oct 31, 2025): A noble approach, but realistically I think phase 2 may be forgotten and we may become stuck in phase 1. I think it's better to do it all at once, label the pull as breaking and then it will be included in the breaking changes for 1.26.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#14832