[API Request] Add readonly and maxAge to the playlist object returned by getPlaylist
#196
Replies: 3 comments 17 replies
-
|
Love this, but not sure about the max age this is a little different from caching for a few of the cases you expose. A maxAge of 1 day, and query the playlist 1 second before the playlist is updated is not that useful. What about And a minRefreshTime, that clearly indicate that clients should not refresh before that duration, unlike maxAge that sounds more like a suggestion. |
Beta Was this translation helpful? Give feedback.
-
|
Would |
Beta Was this translation helpful? Give feedback.
-
|
So readonly=true is basically an easy shorthand for clients to say that you can not use updatePlaylist function with this list? If there is support for adding/removing songs to the playlist but not editing name is that still read only? (If it was just a simple all or nothing I'm fine with that.) For maxAge you could just show the current time instead of 0 so there's always a time? I like this idea as there are smart lists i have that take forever to load but rarely change content so being able to skip them in the client would be a great add. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Type of change
API tweak
Proposal description
Summary
This proposal adds two optional attributes to the existing playlist object returned by
getPlaylist(and therefore to the playlist schema used across responses such asplaylistandplaylistWithSongs).readonly(boolean): signals that a playlist is not intended to be modified by clients.maxAge(integer seconds): signals how long the playlist contents can be treated as fresh (cache lifetime), inspired by HTTPCache-Control: max-age.These fields are additive and backward compatible.
Motivation
Some servers want to expose playlists whose contents are generated or maintained by the server itself, not edited by the user. Examples include:
Two practical problems show up for clients today:
Clients cannot reliably determine whether a playlist is intended to be user editable. Many clients will show edit actions by default, and the user discovers the playlist is not meant to be changed only after failures or surprising behavior.
For generated playlists, clients have no standard hint for refresh cadence. That leads to overfetching (wasted server work and bandwidth) or underfetching (stale results). This is especially painful for large playlists and offline first clients.
Proposed additions
1)
readonlyfalseClient guidance
readonly=true, clients should hide or disable UI actions that modify the playlist, including renaming, reordering, adding tracks, removing tracks, or clearing the playlist.Server guidance
readonly=truefor playlists whose contents are owned by server logic (smart playlists, recommendation mixes, periodic playlists, curated system lists).2)
maxAgegetPlaylist. Clients may cache the playlist result and avoid refetching until the cached copy is older thanmaxAgeseconds.This is intentionally a relative lifetime (seconds) instead of an absolute timestamp. That keeps it aligned with HTTP caching semantics and avoids clock skew issues.
Client guidance
maxAgeis present andmaxAge > 0, clients may treat the playlist contents as fresh formaxAgeseconds starting from the time the response was received.maxAge == 0, clients should treat the response as immediately stale (effectively no caching).Server guidance
maxAgewhen they can reasonably expect the playlist contents to remain stable for that period.maxAgeis especially useful when the server intentionally refreshes the generated contents on a cadence (for example daily or weekly), or when generation is expensive and results are cached.Backward compatibility impact
Backward compatibility
API details
{ "id": "800000075", "name": "Weekly Exploration", "owner": "johndoe", "public": true, "created": "2026-01-24T03:18:41+00:00", "changed": "2026-01-24T03:18:41+00:00", "songCount": 50, "duration": 14523, "readonly": true, "maxAge": 86400, "entry": [ { "id": "300000060", "title": "BrownSmoke" } ] }Security impacts
None
Potential issues
No response
Alternative solutions
No response
Beta Was this translation helpful? Give feedback.
All reactions