Repository navigation
refactor: call the handle a handle in the API - #1179
Conversation
The API sent each user's handle twice, as handle and as username for older clients, and the who-to-follow filter took it as username. It now only says handle: user resources and mention positions drop username, and the suggestions filter is ?handle=.
|
No actionable comments were generated in the recent review.
 |
| Layer / File(s) | Summary |
|---|---|
Handle-based requests and lookup app/Http/Requests/ListApiSuggestedUsersRequest.php, tests/Feature/Controllers/Api/SuggestedUserControllerTest.php, tests/Feature/Controllers/Api/SuggestionDismissalControllerTest.php, DESIGN.md, KNOWLEDGE_BASE.md, PRODUCT.md |
Suggested-user validation and profile lookup use handle instead of username. Documentation uses {handle} in profile, API, feed, activity-graph, and commit-page URLs, and describes the login as a handle. |
Handle-only response payloads app/Http/Resources/UserResource.php, app/Services/Mentions.php, tests/Feature/Controllers/Api/*, tests/Unit/Services/MentionsTest.php |
User resources and mention results no longer include username. API response and mention test expectations use handle and retain the existing mention offset and length fields. |
Priority:
Estimated code review effort: 2 (Simple) | ~10 minutes
Possibly related issues
- Official OpenAPI Documentation for
/api/v1and/api/cli#857: The API field and query parameter updates align with the issue’s request for documentation that reflects current API changes.
Possibly related PRs
- dev-null-sh/dev-null.sh#1156: This PR continues the identity contract migration by removing the compatibility field and using
handlefor API lookups. - dev-null-sh/dev-null.sh#1175: Both PRs update suggested-user validation and profile lookup to use
profiles.handle. - dev-null-sh/dev-null.sh#1178: This PR renames the suggested-user API parameter to
handleand removes the legacy response field.
Suggested reviewers: nunomaduro, taldres
Merge Risk: 
41f72
-
The change renames the API's user handle field and the suggested-users filter without a compatibility layer. No in-repo caller still depends on the old name. Clients outside this repository, notably the mobile app, must read handle before this ships, as the author states. That coordination is a release-timing matter and does not block the merge.
Security architecture risk: 
41f72
-
This intentionally breaks older API clients. The inspected changes preserve existing lookup and access-control behavior, but readiness of the mobile client and other external consumers has not been verified.
Retained concerns
No architecture-level concerns identified.Security review details
-
Security Blast Radius
- inferred — The inspected security-relevant reach is the existing authenticated suggestion-selection path and existing user and mention response consumers. The renamed request key reaches the same profile identity set as before; removal of a duplicate response key does not itself add identity data or authority.
Trust Boundaries and Controls
- observed — The suggested-users route remains under required signed-request authentication. The unchanged query retains blocked-context clearing, candidate exclusions, and viewer-visible commit filtering. Profile-context lookup itself lacks a viewer visibility predicate, but the base username lookup had the same behavior and exposure.
-
Pre-merge checks: 
-
Check name Status Explanation Resolution Docstring Coverage Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 8 files. (3 skipped: 3… Write docstrings for the functions missing them to satisfy the coverage threshold. -
Check name Status Explanation Description Check Check skipped - CodeRabbit’s high-level summary is enabled. Title check The title clearly identifies the main API change: replacing usernamewithhandle.Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 8 files. (3 skipped: 3 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
-
Finishing Touches: 💡 1
-
📝 Generate docstrings: 💡
-
- Commit to this branch
- Create a new PR
🧪 Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Comment @coderabbitai help to get the list of available commands.
Summary
The API sent each user's handle twice, as
handleand asusernamefor older clients, and the who-to-follow filter took it as?username=. It now only sayshandle. Breaking for API clients, on purpose: no compatibility kept.username.mentionson commits, messages and commit previews) dropusername.GET /api/v1/suggested-userstakes?handle=instead of?username=. An old client sendingusernamenow gets the plain suggestions./@{handle}paths.Validation
Local, isolated Postgres:
composer test:lint,composer test:type-coverage: passbun run test:unit: 190/190,tsc --noEmit: cleanpest --parallel --ci --coverage --exactly=100.0: 4492/4492, 100% coverageIndependent review
Agent review of the rename: CODE: PASS. No other place in the API sends or accepts
usernamefor the handle (GitHub logins and the Open Graphprofile:usernametag are left alone). Visual review not applicable.Limitations
The mobile app must read
handlebefore this ships.Summary by CodeRabbit
handleinstead ofusername. Mention data includeshandle,offset, andlength; the duplicateusernamefield is no longer returned.handleas the query parameter.{handle}terminology.