docs(artists): GET /api/artists/{id}/profile — public artist profile contract

Merged
SW
2mo ago
+141-0

Contract for the public artist profile page — row 1 of recoupable/chat#1963's PR matrix. Approved design: Artist Profile Page canvas.

What this documents

GET /api/artists/{id}/profile — public, no authentication, unbilled. One call returns everything the page renders:

{
  "id": "…", "name": "…", "image": "https://…",
  "socials": [{ "type": "SPOTIFY", "username": "…", "profile_url": "https://…" }],
  "catalogs": [{ "id": "…", "name": "…", "song_count": 24, "updated_at": "…" }]
}
  • 404 semantics are contract: unknown id and not-an-artist return the same 404, documented as deliberately indistinguishable so the endpoint cannot probe which account ids exist.
  • No 401/402 documented — the description states the endpoint is deliberately public and unbilled.
  • Cacheability documented: Cache-Control: public, s-maxage=300, stale-while-revalidate=600, with the may-be-minutes-stale caveat.
  • Three new schemas (ArtistPublicProfileResponse, …Social, …Catalog); the 404 reuses the existing ArtistSocialsErrorResponse shape. New reference page api-reference/artists/profile.mdx + docs.json nav entry after Artists → List.

Verification

  • releases.json and docs.json parse after anchored text edits (this spec does not round-trip through json.dumps, so edits are inserted at brace boundaries; diff is purely additive).
  • Naming avoids the existing unreferenced ArtistProfile schema in the same spec (research-side shape) — the new schemas are ArtistPublicProfile*.
  • The response shape matches the issue's Goal field-for-field; the api PR (row 2) implements exactly this.

Merge order

First of the three: docs → api → chat, per house convention. The api implementation follows in row 2 of chat#1963.

Summary by cubic

Documents a public endpoint, GET /api/artists/{id}/profile, that returns an artist’s name, image, socials, and linked catalogs in one unauthenticated, unbilled call for the shareable artist page. It sets cache and 404 semantics to prevent account enumeration.

Review focus

  • Response schemas: ArtistPublicProfileResponse, ArtistPublicProfileSocial, ArtistPublicProfileCatalog; avoids the research-side ArtistProfile schema.
  • Endpoint semantics: public, unauthenticated, unbilled; cache policy Cache-Control: public, s-maxage=300, stale-while-revalidate=600.
  • 404 behavior: unknown ids and non-artist accounts return the same 404 using ArtistSocialsErrorResponse.
  • Docs: new api-reference/artists/profile.mdx and docs.json nav entry after Artists → List. Page title is “Get Artist Profile” (drops “(Public)”).

Rollout

  • Merge order: docs → api → chat. No client migration.

Summary by CodeRabbit

  • New Features

    • Added a public artist profile endpoint accessible without authentication.
    • Artist profiles include profile details, social links, and associated catalogs.
    • Added artist ID validation and documented caching behavior.

  • Documentation

    • Added artist profile API reference documentation to the Artists navigation.