REST polish: return 200 on empty collection, add Location header on POST, add detail to 409

[nanotaboada]

Problem

Three low-severity REST compliance gaps identified during a full RESTful audit:

1. GET /players returns 404 Not Found when the collection is empty instead of 200 OK []
2. POST /players returns 201 Created without a Location header pointing to the new resource
3. POST /players returns 409 Conflict with no detail message, giving clients no programmatic context

Proposed Solution

Fix each gap independently:

1. Return 200 OK with an empty list [] when no players exist — a 404 implies the resource itself is absent, not that it is empty
2. Add a Location response header on 201, e.g. response.headers["Location"] = f"/players/squadnumber/{player.squad_number}"
3. Add detail="A Player with this squad number already exists." to the 409 HTTPException

Suggested Approach

All changes are confined to routes/player_route.py:

• Empty collection (GET): change the 404 branch to return JSONResponse(status_code=200, content=[]) or equivalent
• Location header (POST): append header to the response after successful creation
• 409 detail (POST): add detail= kwarg to the existing raise HTTPException(...)

Acceptance Criteria

• GET /players returns 200 OK with [] when no players exist (not 404)
• POST /players 201 response includes a Location header pointing to the created resource
• POST /players 409 response includes a human-readable detail message
• Tests updated to cover the empty-collection case and assert the Location header
• All pre-commit checks pass (flake8, black, pytest, coverage ≥ 80%)

References

• RFC 7231 §7.1.2 — Location header on 201: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.2
• REST convention: collection endpoints return 200 [] on empty, not 404

[coderabbitai]

🔗 Related PRs

#489 - refactor(tests): adopt action-oriented naming convention [merged]
#494 - Replace Postman collection with .rest file [merged]
#524 - refactor(api): use squad number for PUT and DELETE endpoints [merged]
#532 - feat(api): enforce squad number immutability on PUT [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!