[REFACTOR] Add explicit /squadNumber/ path segment to GET, PUT and DELETE routes

[nanotaboada]

Problem

The GET, PUT, and DELETE endpoints that look up a player by squad number expose the value directly at /players/{value}, relying on ASP.NET Core's :int route constraint to disambiguate them from the /players/{id:Guid} endpoint. This leaks a framework-specific implementation detail into the URL design — a REST client has no way to know the path accepts only integers without prior knowledge of the framework.

Proposed Solution

Scope the squad number under a dedicated path segment, making the URL self-describing and decoupled from ASP.NET Core's type-constraint disambiguation mechanism:

GET    /players/squadNumber/9
PUT    /players/squadNumber/9
DELETE /players/squadNumber/9

Suggested Approach

Update the route templates in PlayerController.cs:

- [HttpGet("{squadNumber:int}", Name = "RetrieveBySquadNumber")]
+ [HttpGet("squadNumber/{squadNumber:int}", Name = "RetrieveBySquadNumber")]

- [HttpPut("{squadNumber:int}", Name = "Update")]
+ [HttpPut("squadNumber/{squadNumber:int}", Name = "Update")]

- [HttpDelete("{squadNumber:int}", Name = "Delete")]
+ [HttpDelete("squadNumber/{squadNumber:int}", Name = "Delete")]

Then update README.md to reflect the new paths:

- - `GET /players/{squadNumber:int}` - Get player by squad number
- - `PUT /players/{squadNumber:int}` - Update player
- - `DELETE /players/{squadNumber:int}` - Remove player
+ - `GET /players/squadNumber/{squadNumber:int}` - Get player by squad number
+ - `PUT /players/squadNumber/{squadNumber:int}` - Update player
+ - `DELETE /players/squadNumber/{squadNumber:int}` - Remove player

Acceptance Criteria

• GET /players/squadNumber/{squadNumber:int} returns the correct player
• PUT /players/squadNumber/{squadNumber:int} updates the correct player
• DELETE /players/squadNumber/{squadNumber:int} deletes the correct player
• Old routes (/players/{int}) return 404 Not Found
• README.md API Reference reflects the new paths
• All existing tests pass with the updated routes

References

• REST API Design: Resource Naming
• Affects: src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs (lines 127, 162, 207)
• Affects: README.md — API Reference section

[coderabbitai]

🔗 Related PRs

#206 - refactor(tests): more idiomatic Fake methods and result assertions [merged]
#208 - feature/identifiers [merged]
#334 - feat: add 15 substitute players to database via migration [merged]
#352 - refactor: consolidate player data into single source of truth (#210) [merged]
#399 - refactor(tests): rename test methods to Microsoft naming standard [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Modify three route template attributes in PlayerController.cs to add the squadNumber/ path segment prefix
• Update README.md API Reference to document the new route structure with the :int constraint
• Only two files are modified: PlayerController.cs and README.md
• No test modifications required since route names and parameter names remain unchanged

Implementation Steps

Update Route Structure and Documentation

This phase updates the route templates to add the explicit squadNumber/ path segment and ensures documentation reflects the new API contract. Only two files are in scope: PlayerController.cs and README.md.

Task 1: Update Route Templates in PlayerController

Modify the route attribute templates for the three squad-number-based endpoints to include the squadNumber/ path segment prefix.

• Update src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs line 127: Change [HttpGet("{squadNumber:int}", ...)] to [HttpGet("squadNumber/{squadNumber:int}", ...)]
• Update line 162: Change [HttpPut("{squadNumber:int}", ...)] to [HttpPut("squadNumber/{squadNumber:int}", ...)]
• Update line 207: Change [HttpDelete("{squadNumber:int}", ...)] to [HttpDelete("squadNumber/{squadNumber:int}", ...)]
• Preserve the existing named routes ("RetrieveBySquadNumber", "Update", "Delete") and parameter names unchanged
• The CreatedAtRoute call in the POST endpoint (lines 61-65) requires no modification since it references the route by name and the route value key squadNumber remains the same

Task 2: Update API Reference Documentation

Update the README.md API Reference section to reflect the new route paths.

• Update README.md around lines 221-224 in the API Reference section
• Update the three affected endpoint paths to the new format with explicit path segment and :int constraint:
  • GET /players/squadNumber/{squadNumber:int} - Get player by squad number
  • PUT /players/squadNumber/{squadNumber:int} - Update player
  • DELETE /players/squadNumber/{squadNumber:int} - Remove player
• Maintain consistency with the existing documentation format and descriptions

🤖 Prompt for AI agents

Update route templates in `PlayerController.cs` and reflect the changes in
`README.md`. The goal is to make the squad-number lookup dimension explicit in
the URL by adding a `squadNumber/` path segment prefix to the three affected
endpoints. Only two files are in scope.

**`src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs`**
- Line 127: Change the `[HttpGet]` route attribute from `"{squadNumber:int}"` to
`"squadNumber/{squadNumber:int}"` — preserve the existing named route
`"RetrieveBySquadNumber"` and all other attribute arguments
- Line 162: Change the `[HttpPut]` route attribute from `"{squadNumber:int}"` to
`"squadNumber/{squadNumber:int}"` — preserve the existing named route `"Update"`
and all other attribute arguments
- Line 207: Change the `[HttpDelete]` route attribute from `"{squadNumber:int}"`
to `"squadNumber/{squadNumber:int}"` — preserve the existing named route
`"Delete"` and all other attribute arguments
- Do NOT modify the `CreatedAtRoute` call in the POST endpoint (lines 61-65); it
references the route by name and the route value key `squadNumber` is unchanged

**`README.md`**
- Around lines 221-224 in the API Reference section, update the documented paths
for the three affected endpoints to the new format including the explicit path
segment and `:int` constraint:
  - `GET /players/squadNumber/{squadNumber:int}` - Get player by squad number
  - `PUT /players/squadNumber/{squadNumber:int}` - Update player
  - `DELETE /players/squadNumber/{squadNumber:int}` - Remove player
- Maintain consistency with the existing documentation format and descriptions

After completing changes, verify that all existing unit tests in
`PlayerControllerTests.cs` pass without modification, since the route names
(`"RetrieveBySquadNumber"`, `"Update"`, `"Delete"`) and parameter names
(`squadNumber`) remain unchanged.

Research

The project is an ASP.NET Core Web API with attribute-routed controllers. The PlayerController.cs defines all player endpoints under the base route /players. Three endpoints currently use {squadNumber:int} directly after the base path for GET (line 127), PUT (line 162), and DELETE (line 207) operations. The POST endpoint uses a named route "RetrieveBySquadNumber" in its CreatedAtRoute response, which references the GET-by-squad-number endpoint. The test suite is entirely unit-based with no integration tests making HTTP requests to URL paths. One unit test asserts the route name and route value key, but since neither the route name nor the parameter name is changing, tests require no modification.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Update route templates in `PlayerController.cs` and reflect the changes in
`README.md`. The goal is to make the squad-number lookup dimension explicit in
the URL by adding a `squadNumber/` path segment prefix to the three affected
endpoints. Only two files are in scope.

**`src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs`**
- Line 127: Change the `[HttpGet]` route attribute from `"{squadNumber:int}"` to
`"squadNumber/{squadNumber:int}"` — preserve the existing named route
`"RetrieveBySquadNumber"` and all other attribute arguments
- Line 162: Change the `[HttpPut]` route attribute from `"{squadNumber:int}"` to
`"squadNumber/{squadNumber:int}"` — preserve the existing named route `"Update"`
and all other attribute arguments
- Line 207: Change the `[HttpDelete]` route attribute from `"{squadNumber:int}"`
to `"squadNumber/{squadNumber:int}"` — preserve the existing named route
`"Delete"` and all other attribute arguments
- Do NOT modify the `CreatedAtRoute` call in the POST endpoint (lines 61-65); it
references the route by name and the route value key `squadNumber` is unchanged

**`README.md`**
- Around lines 221-224 in the API Reference section, update the documented paths
for the three affected endpoints to the new format including the explicit path
segment and `:int` constraint:
  - `GET /players/squadNumber/{squadNumber:int}` - Get player by squad number
  - `PUT /players/squadNumber/{squadNumber:int}` - Update player
  - `DELETE /players/squadNumber/{squadNumber:int}` - Remove player
- Maintain consistency with the existing documentation format and descriptions

After completing changes, verify that all existing unit tests in
`PlayerControllerTests.cs` pass without modification, since the route names
(`"RetrieveBySquadNumber"`, `"Update"`, `"Delete"`) and parameter names
(`squadNumber`) remain unchanged.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[nanotaboada]

@coderabbitai adjust plan to reflect updated specs

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!