[API Request] getYears

[gravelld]

Type of change

API tweak

Proposal description

Many music clients want to browse musical elements by a time period. Typically, they seek first to display a list of years or decades, then after selecting a time period the musical elements (albums, songs) are displayed.

Currently there's no operation to list the years of release covered in a collection. getGenres is analogous as a listing of all groups for a different type of classification.

A current workaround is to use getAlbumListx and inspect the year properties for the returned elements. However, this is suboptimal, performance wise, because to know all years you must request all albums (there's no ordering by year - byYear appears to be a filter, not a sort. newest and recent are not explicit as to whether all albums are returned).

I'm not sure if this is incorrect but I classified this as a API tweak because, whilst it's a significant addition, it shouldn't require the "extensions" mechanism (I don't feel).

Backward compatibility impact

This would be additive so there should be no backwards compatibility issues.

Backward compatibility

• No backward compatibility impact.

API details

getYears

Returns all years in the music library.

Parameters

All parameters are optional.

type

The type of year being queried. Possible values: releaseDate, originalReleaseDate.
Default: releaseDate

size

The maximum length of the returned list.
Default: 10

offset

The offset in the list from which the list should start.
Default: 0

Response

years

Array of year. Required.

year

All fields are required.

songCount

The number of songs in that year.

albumCount

The number of albums in that year.

value

The title of the time period.

Example

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true
    "years": {
      "year": [
        {
          "songCount": 125,
          "albumCount": 11,
          "value": "1970"
        },
        {
          "songCount": 149,
          "albumCount": 13,
          "value": "1984"
        }
      ]
    }
  }
}

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[dweymouth]

This will require an extension, as any new API call does, so clients can query whether the server supports it or not. But I do think this would be a nice addition. As would the ability to filter and retrieve albums by recordLabel as well (though maybe that should be a new extension instead of included in this). eg getRecordLabels and a new recordLabel filter to getAlbumList2

[Tolriq]

There's a million needed filters and sorts for the getXXXX hence the new endpoints.

[gravelld]

I think it makes sense to have the other lists as separate requests to keep these tickets SMART.

[Tolriq]

Not necessarily as we are collecting global needs for the new endpoints.
This can for example lead to the question about songCount and albumCount being important or not, allowing to build a generic API to query distinct values of fields for songs and albums.

[Tolriq]

Currently with the API we have the type parameter makes little sense as we can't change the byYear filter to something else.
So if it was to be added now before the new endpoints with proper filtering, the getYears should return years that works for the byYear filter, so that match the year of the albums and not the new OS fields.

In the same idea if it was to be done before the new endpoints it would make sense that this does not have pagination as there's only a limited amount of possible years anyway.

But yes as dweymouth mentioned with proper filtering on the new endpoints to access the data, getting access to those kind of list will be the final touch.

[gravelld]

I don't quite understand your English here.

Currently with the API we have the type parameter makes little sense as we can't change the byYear filter to something else.

Are you saying type makes little sense on getAlbumsList2? Or type should be renamed? This isn't proposing changing the byYear filter.

So if it was to be added now before the new endpoints with proper filtering, the getYears should return years that works for the byYear filter, so that match the year of the albums and not the new OS fields.

Is "it" this new API method? Or are you referring to byYear?

it would make sense that this does not have pagination as there's only a limited amount of possible years anyway.

I can accept that - I added it in for future use. As API designers I'm not sure if we can ever prescribe that there will definitely be a limited amount of possible years, but I agree having a finite, fairly small list is by far the likeliest use case so happy with that.

[Tolriq]

It's missing 2 coma, but the English is fine.

Currently, with the API we have, the type parameter makes little sense as we can't change the byYear filter to something else.

This means that since the byYear filter is based on the year field and can't be changed, passing a type to get years that correspond to other years makes no sense since there's 0 usage for them.

If you have 1 album with year 2000 and originalRelease date to 1998-10-01, your API would return 1998 and you would not be able to do anything from it since you need to pass 2000 to the byYear filter to get that album.

And so yes it points to this API.