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

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

id	title	status	assignee	created_date	updated_date	labels	dependencies	references	priority
ML-152	Add API version prefix to collection endpoints	Done		2026-04-30 10:48	2026-04-30 10:57	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

Implementation Plan

Implementation Plan

Scope: Version ALL routes under /api to /api/v1/, not just collection endpoints. Affected routes:

• /api/v1/collection
• /api/v1/collection/latest
• /api/v1/collection/random
• /api/v1/collection/on_this_day
• /api/v1/assets/:transform_payload
• /api/v1/backup

Decision: Remove old routes (no 301 redirects) — user controls all consumers.

Files to change:

1. lib/music_library_web/router.ex — Move all routes from /api to /api/v1
2. test/music_library_web/controllers/collection_controller_test.exs — Update paths to /api/v1/collection/*
3. test/prod.hurl — Update /api/collection/latest → /api/v1/collection/latest
4. docs/architecture.md — Update route table entries for CollectionController, AssetController (API route), ArchiveController (API route)
5. Asset controller tests (if any) — Check for /api/assets/ references

Implementation Notes

Implementation complete

Files changed

1. lib/music_library_web/router.ex — Changed scope "/api" to scope "/api/v1" for all 6 API routes (collection × 4 + assets + backup). Old routes removed per user decision.

2. lib/music_library_web/controllers/collection_json.ex — Updated cover_url and thumb_url path sigils from ~p"/api/assets/..." to ~p"/api/v1/assets/...".

3. test/music_library_web/controllers/collection_controller_test.exs — Updated all 4 route paths, 4 describe strings, and 2 expected JSON URLs to /api/v1/....

4. test/prod.hurl — Updated both API references from /api/collection/latest to /api/v1/collection/latest.

5. docs/architecture.md — Updated ArchiveController, AssetController, and CollectionController route entries to /api/v1/....

Test results

CollectionControllerTest: 5 passed
AssetControllerTest:      9 passed
ArchiveControllerTest:    1 passed