[DaveBlake]

I thought I would try to keep an up-to-date list of all changes made to the JSON API since the release of Kodi Krypton and v8.0.0. These can be researched in more detail via the related PRs in Git, but a forum post is to help visiblity to JSON consumers

Worth noting that since Frodo a versioning system (<major>.<minor>.<patch>) has been applied to the JSON-RPC API. <patch> part of the version is  increased on any changes to the internal implementation but not to the API definition. <minor> version is increased (and the <patch> reset to 0) on backwards compatible additions/changes to the API definition. <major> version is  increased on breaking backwards incompatible changes to the API definition. In practice, to avoid runaway major version numbers, the major version will only be bumped on the first breaking change to the API, with any subsequent breaking changes prior to the next release of Kodi being taken as minor version steps. Then on release of Leia a final major version step will be made.

A major change for Leia onwards is that JSON-RPC no longer accepts many of the commands via HTTP. This is a measure taken for improved security, but no doubt will inconvenience a number of JSON consumers. Although Kodi still accepts HTTP GET requests to JSON it limits all non-POST requests to ReadData permissions only. So when trying to call a modifying JSON-RPC method like Player.PlayPause the following error will be returned:

Code:

{
"jsonrpc": "2.0",
"error": {
"code": -32099,
"message": "Bad client permission."
},
"id": 1
}

To make any data modifications you will need to use HTTP POST.
See https://github.com/xbmc/xbmc/pull/12281 for more details.
Slightly oddly such a change was not accompanied by any API version change.

8.1.0
Settings.GetSettings additionally returns date and time for each setting.
1st Jun 2017 https://github.com/xbmc/xbmc/pull/12125

8.2.0
Add read only control label Setting.Details.ControlLabel
9th Jun 2017 https://github.com/xbmc/xbmc/pull/12276

8.3.0
New "added" field for VideoLibrary.OnUpdate and MusicLibrary.OnUpdate notification, returned true if it is announced for a newly added media item.
17th Jul 2017 https://github.com/xbmc/xbmc/pull/10916

Incidentally https://github.com/xbmc/xbmc/pull/12936 changed version.txt, prefixing the version number with JSONRPC_VERSION

8.4.0
Add new fields and corrections for AudioLibary methods:

• Add new artist fields  "sortname", "type", "gender", "disambiguation", optionally returned by GetArtists() and GetArtistDetails().
  
• Add new album fields  "sortartist", "musicbrainzreleasegroupid" , optionally returned by GetAlbums() and GetAlbumDetails().
  
• Add new song fields "sortartist", optionally returned by GetSongs().
  Corrections to Audio.Details.Media:
  a) "musicbrainzalbumid" is only returned for albums, deprecated for songs (always been empty).
  b)"musicbrainzalbumartistid" is already (correctly) returned as a string array so fix type to match.
  

4th Nov 2017 https://github.com/xbmc/xbmc/pull/12963

8.4.1
Fix wrong playback order for smartplaylists, playlists and upnp.
This was a long standing bug where queueing playlists (.m3u files etc.), smartplaylists (.xsp) and upnp items using Playlist.Add() or Playlist.Open() with "directory" parameter results in items in an unexpected and order. The order defined in the smartplaylist, and the actual order of files listed in the .m3u etc. file wass ignored.
17th Nov https://github.com/xbmc/xbmc/pull/13059

8.5.0
Add parameter to VideoLibrary.Clean to optionally clean just movies, tvshows, or musicvideos
20th Nov 2017 https://github.com/xbmc/xbmc/pull/13026

9.0.0
Breaking changes. Fixes to a number of long standing faults in the API access to the music library and a tidy-up of types and parameters removing some deprecated fields.

GetAlbums() and GetAlbumDetails()
The "genre" and "genreid" array values previously returned were not guarenteed to match, to resolve this album genre handling has been brought inline with artist genre handling. The "genreid" field has been removed. The "genre" field values are album genres - these may match that of the songs on the album, or can be replaced via scraping with entirely different strings that are not codified with IDs. A new field "songgenres", an array of {title, id} pairs of matching song genre strings and id, has been added. This returns the union of song genres all the songs on the album.

Matching song genre values and ids are still returned in separate fields ("genreid" and "genre") by GetSongs(). These have been kept separate because fetching "genreid" requires extra queries and takes longer, whereas genre values can be returned without additional time. To recap: for artists "genre" is artist genres, for albums it is album genres and they both have "songgenres" field, for songs "genre" is song genres and songs also have a "genreid" field.

API consumers that want genre values for artists or albums that enable them to replicate Kodi genre filtering, use "songgenres" - a matching pairs of string and id.

SetAlbumDetails() and SetSongDetails()
Setting of both artists and genres by these methods has been fixed.
- Add parameters "musicbrainzalbumartistid" (string array) and "displayartist" to `SetAlbumDetails()`
- Remove album properties: "albumartist", "album", "musicbrainzalbumid", "musicbrainzalbumartistid" from `SetSongDetails()`
- Add string parameters "displayartist", "sortartist", "mood" to `SetSongDetails()`.
But of course, tags scanned from updated music files will always overwrite and changes made by API.

26th Nov 2017 https://github.com/xbmc/xbmc/pull/13051

9.1.0
Add "art" parameter to AudioLibrary get and set methods to get/set any type of artwork for artists, albums and songs.
30th Dec 2017 https://github.com/xbmc/xbmc/pull/13101

9.1.1
Fix Favorites.GetFavorites regression. Broken by the favorites refactoring of #11967 - "type", "window" and "windowparameters" were being returned incorrectly.
4th Feb 2018 https://github.com/xbmc/xbmc/pull/13410

9.2.0
Breaking change (major verion left at 9 as during alpha)
Add player OnResume, OnAVChange and OnAVStart notifications. Be aware that OnPlay will only be called at start of playback now and not when resuming playback.
8th April 2018 https://github.com/xbmc/xbmc/pull/13726

9.2.1
Fix Audiolibrary.GetAlbums() return of "songgenres" values.
26th May 2018 https://github.com/xbmc/xbmc/pull/13938

9.3.0
Non-breaking additions to the AudioLibrary interface:

• Add "librarylastupdated" property to GetProperties that returns when the music library was last updated by scanning music files or scraping additional info for artists or albums. This will provide better support for JSON consumers trying to sync with updates to the music library.
  
• Add "singlesonly" param to GetSongs to fetch only singles.
  
• Add "lastplayed" field for GetAlbums and GetAlbumDetails previously ommited by accident
  

8th June 2018 https://github.com/xbmc/xbmc/pull/13969

9.4.0
Non-breaking additions to the AudioLibrary interface for music sources:

• Add GetSources method to fetch all music sources, including a unique ID returned in other methods
  
• Add "sourceid" field, an array of integers, to GetArtists, GetArtistDetails, GetAlbums, GetAlbumDetails, GetSongs, GetSongDetails and GetGenres
  

13th June 2018 https://github.com/xbmc/xbmc/pull/14012

9.4.1
Fix playing video streams from URLs with options regression. See https://trac.kodi.tv/ticket/17914 for explanantion.
18th Jun 2018 https://github.com/xbmc/xbmc/pull/14068

9.4.2
Internal improvements to AudioLibrary GetArtists, GetAlbums, and GetSongs methods making JSON access to music data considerably faster (5 x) and fixing a number of errors and inconsistencies e.g. empty fields not being returned at all.
15th July 2018 https://github.com/xbmc/xbmc/pull/14060

9.4.3
Internal processing fix for AudioLibrary GetAlbums and GetSongs methods filter processing. Resolves issues with filtering by path, playcount, lastplayed and dateadded rules.
20th July 2018 https://github.com/xbmc/xbmc/pull/14201

9.4.4
Minor internal AudioLibrary fixes to ensure JSON API results matches schema definition:
Fix AudioLibrary.GetSources to always return "file" property and call results "sources" as schema defines.
Fix AudioLibrary.GetGenres to process "sourceid" property correctly.
24th July 2018 https://github.com/xbmc/xbmc/pull/14222

9.5.0
Add "useartistsortname" sort property and "sorttokens" and "language" as application properties to bring API sort options in line with those available via GUI.
Assorted other sorting related fixes:

• Fix random sort order when requested fields mean SQL joins are used
  
• Fix random sort SQL to adjust to MySQL syntax when necessary
  
• Apply ignore articles and use artist sortname sort attributes
  
• Fix case insensitive sorting on SQLite
  
• Implement natural order for text that starts with digits
  

27th July 2018 https://github.com/xbmc/xbmc/pull/14277

9.5.1
Internal processing fix for MySQL 8.0.12 issue with SQL used for AudioLibrary.GetArtists
5th August 2018 https://github.com/xbmc/xbmc/pull/14268

9.5.2
Internal processing fix to playback of pvr channels and pvr recordings. See https://trac.kodi.tv/ticket/17984
15th August 2018 https://github.com/xbmc/xbmc/pull/14301

9.6.0
Non-breaking addition to Player.GetActivePlayers to return "playertype" (external, remote, internal)
20th August 2018 https://github.com/xbmc/xbmc/pull/14315

9.6.1
Internal fix to avoid seg fault crashes when Player.GetItem call coincided with track change
24th September 2018 https://github.com/xbmc/xbmc/pull/14454

9.7.0
Non-breaking addition to VideoLibrary.SetMovieSetDetails to set plot for movie sets, and to VideoLibrary.SetSeasonDetails and VideoLibrary.GetSeasonDetails to set/get title
20th October 2018 https://github.com/xbmc/xbmc/pull/14523

9.7.1
Internal fix for AudioLibrary.GetArtists to correctly return artists with no art when only one of "thumbnail" or "fanart" properties are requested.
25th October 2018 https://github.com/xbmc/xbmc/pull/14710

9.7.2
Internal fix for Addons.GetAddons and GetAddonDetails to correctly return "broken" field. This was temporarily incorrect for the previous 3 days of nightly builds.
30th October 2018 https://github.com/xbmc/xbmc/pull/14738

Between 11th Nov and 17th Nov the Windows nightly builds had an issue with returning JSON schema version as "0.7.2" rather than "9.7.2". This has been resolved by https://github.com/xbmc/xbmc/pull/14899

10.0.0
Bump major version for release of v18 RC1
17th October 2018 https://github.com/xbmc/xbmc/pull/14790

10.0.1
Internal fix for PVR.Record
20th December 2018 https://github.com/xbmc/xbmc/pull/15093

10.1.0
Non-breaking addition of VideoLibrary.OnRefresh notification
30th December 2018 https://github.com/xbmc/xbmc/pull/15156

10.2.0
Non-breaking addition of Player.SetViewMode and Player.GetViewMode
22nd Feb 2019 https://github.com/xbmc/xbmc/pull/15477

Please keep this thread clean. It should be an easy overview for  JSON-RPC API consumers.
For discussions / feature requests / bugreports, please find (or create) the appropriate thread in the JSON_RPC forum.[/b][/b]

[DaveBlake]

#Reserved

[DaveBlake]

Bump to 9.0.0 - breaking changes

[DaveBlake]

Bump to 9.1.0 - adding audio library get/set "art" for artists, albums and songs

[DaveBlake]

Bump to 9.1.1 - internal processing fix to restore GetFavorites functionality after regression

[DaveBlake]

Bump to 9.2.0 - Breaking changes . Add player OnResume, OnAVChange and OnAVStart notifications.
Be aware that OnPlay will only be called at start of playback now and not when resuming playback.

[DaveBlake]

Bump to 9.2.1 - internal processing fix for return of "songgenres" values by  Audiolibrary.GetAlbums()

[DaveBlake]

Bump to 9.3.0 - non-breaking additions to the AudioLibrary interface:
Add "librarylastupdated" property to GetProperties , "singlesonly" param to GetSongs and "lastplayed" field for GetAlbums and GetAlbumDetails.

[DaveBlake]

Bump to 9.4.0 - non-breaking additions to the AudioLibrary interface for music sources:

• Add GetSources method to fetch all music sources, including a unique ID returned in other methods
  
• Add "sourceid" field, an array of integers, to GetArtists, GetArtistDetails, GetAlbums, GetAlbumDetails, GetSongs, GetSongDetails and GetGenres  
  

[DaveBlake]

Bump to 9.4.1 - internal processing fix for playing video streams from URLs with options regression.

[DaveBlake]

Bump to 9.4.2 - reworking of GetArtists, GetAlbums, and GetSongs to be considerably faster

[DaveBlake]

Bump to 9.4.3 - internal processing fix for filter processing on GetSongs and GetAlbums

[DaveBlake]

Bump to 9.4.4 - internal processing fix to AudioLibrary.GetSources to match schema

[DaveBlake]

Bump to 9.5.0 - non-breaking additions to the interface: add "useartistsortname" sort property and "sorttokens" and "language" as application properties to bring API sort options in line with those available via GUI.

[DaveBlake]

Bump to 9.5.1 - internal processing fix for MySQL 8.0.12 issue with SQL used for AudioLibrary.GetArtists