music_library/backlog/tasks/ml-152 - Add-API-version-prefix-to-collection-endpoints.md

id, title, status, assignee, created_date, labels, dependencies, references, priority

id	title	status	assignee	created_date	labels	dependencies	references	priority
ML-152	Add API version prefix to collection endpoints	To Do		2026-04-30 10:48	api versioning		lib/music_library_web/router.ex lib/music_library_web/controllers/collection_controller.ex test/prod.hurl	medium

Description

The JSON API endpoints under /api/collection/* (lib/music_library_web/controllers/collection_controller.ex) have no versioning prefix. If the response shape changes, external consumers would break without warning.

Add a /api/v1/ prefix to all collection API routes:

• /api/v1/collection
• /api/v1/collection/latest
• /api/v1/collection/random
• /api/v1/collection/on_this_day

Keep existing routes as deprecated redirects (301) for backward compatibility, or remove them if there are no known consumers.

Update:

• lib/music_library_web/router.ex (route definitions)
• Controller and JSON tests
• test/prod.hurl (post-deploy verification that uses API endpoints)
• docs/architecture.md (API route table)

Acceptance Criteria

• #1 All collection API routes live under /api/v1/collection/*
• #2 Existing /api/collection/* routes are removed or redirect to v1 with 301
• #3 Controller and JSON tests pass against the new /api/v1/ paths
• #4 test/prod.hurl references updated to new paths
• #5 docs/architecture.md updated with new route paths