From 73a9ac16d69d669a78481f27caa6cd5f342bbac9 Mon Sep 17 00:00:00 2001
From: chme <christian.meffert@googlemail.com>
Date: Sun, 23 Feb 2020 11:40:44 +0100
Subject: [PATCH] [README] Update JSON API docs with playlist folders support

---
 README_JSON_API.md | 78 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 76 insertions(+), 2 deletions(-)

diff --git a/README_JSON_API.md b/README_JSON_API.md
index 316c47f7..5bcd03f7 100644
--- a/README_JSON_API.md
+++ b/README_JSON_API.md
@@ -747,6 +747,7 @@ curl -X PUT "http://localhost:3689/api/queue/items/2"
 | GET       | [/api/library/playlists](#list-playlists)                   | Get a list of playlists              |
 | GET       | [/api/library/playlists/{id}](#get-a-playlist)              | Get a playlist                       |
 | GET       | [/api/library/playlists/{id}/tracks](#list-playlist-tracks) | Get list of tracks for a playlist    |
+| GET       | [/api/library/playlists/{id}/playlists](#list-playlists-in-a-playlist-folder) | Get list of playlists for a playlist folder   |
 | GET       | [/api/library/artists](#list-artists)                       | Get a list of artists                |
 | GET       | [/api/library/artists/{id}](#get-an-artist)                 | Get an artist                        |
 | GET       | [/api/library/artists/{id}/albums](#list-artist-albums)     | Get list of albums for an artist     |
@@ -807,7 +808,7 @@ curl -X GET "http://localhost:3689/api/library"
 
 ### List playlists
 
-Lists the playlists in your library
+Lists all playlists in your library (does not return playlist folders)
 
 **Endpoint**
 
@@ -968,6 +969,76 @@ curl -X GET "http://localhost:3689/api/library/playlists/1/tracks"
 ```
 
 
+### List playlists in a playlist folder
+
+Lists the playlists in a playlist folder
+
+**Note**: The root playlist folder has `id` 0.
+
+**Endpoint**
+
+```http
+GET /api/library/playlists/{id}/playlists
+```
+
+**Path parameters**
+
+| Parameter       | Value                |
+| --------------- | -------------------- |
+| id              | Playlist id          |
+
+**Query parameters**
+
+| Parameter       | Value                                                       |
+| --------------- | ----------------------------------------------------------- |
+| offset          | *(Optional)* Offset of the first playlist to return         |
+| limit           | *(Optional)* Maximum number of playlist to return           |
+
+**Response**
+
+| Key             | Type     | Value                                            |
+| --------------- | -------- | ------------------------------------------------ |
+| items           | array    | Array of [`playlist`](#playlist-object) objects  |
+| total           | integer  | Total number of playlists in the playlist folder |
+| offset          | integer  | Requested offset of the first playlist           |
+| limit           | integer  | Requested maximum number of playlist             |
+
+
+**Example**
+
+```shell
+curl -X GET "http://localhost:3689/api/library/playlists/0/tracks"
+```
+
+```json
+{
+  "items": [
+    {
+      "id": 11,
+      "name": "Spotify",
+      "path": "spotify:playlistfolder",
+      "parent_id": "0",
+      "smart_playlist": false,
+      "folder": true,
+      "uri": "library:playlist:11"
+    },
+    {
+      "id": 8,
+      "name": "bytefm",
+      "path": "/srv/music/Playlists/bytefm.m3u",
+      "parent_id": "0",
+      "smart_playlist": false,
+      "folder": false,
+      "uri": "library:playlist:8"
+    }
+  ],
+  "total": 2,
+  "offset": 0,
+  "limit": -1
+}
+```
+
+
 ### List artists
 
 Lists the artists in your library
@@ -2203,7 +2274,10 @@ curl --include \
 | id              | string   | Playlist id                               |
 | name            | string   | Playlist name                             |
 | path            | string   | Path                                      |
-| smart_playlist  | boolean  | `true` if playlist is a smart playlist   |
+| parent_id       | integer  | Playlist id of the parent (folder) playlist |
+| type            | string   | Type of this playlist: `special`, `folder`, `smart`, `plain` |
+| smart_playlist  | boolean  | `true` if playlist is a smart playlist    |
+| folder          | boolean  | `true` if it is a playlist folder         |
 | uri             | string   | Resource identifier                       |