From d4264bca294edf85d26e6d39d9292eb320867859 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Mon, 26 Nov 2018 18:15:48 +0100
Subject: [PATCH] Fix #575: Documented which Subsonic endpoints are implemented

---
 changes/changelog.d/575.enhancement |  1 +
 docs/developpers/index.rst          | 15 +++++++
 docs/developpers/subsonic.rst       | 70 +++++++++++++++++++++++++++++
 docs/index.rst                      |  3 +-
 4 files changed, 87 insertions(+), 2 deletions(-)
 create mode 100644 changes/changelog.d/575.enhancement
 create mode 100644 docs/developpers/index.rst
 create mode 100644 docs/developpers/subsonic.rst

diff --git a/changes/changelog.d/575.enhancement b/changes/changelog.d/575.enhancement
new file mode 100644
index 00000000..eb1781de
--- /dev/null
+++ b/changes/changelog.d/575.enhancement
@@ -0,0 +1 @@
+Documented which Subsonic endpoints are implemented (#575)
diff --git a/docs/developpers/index.rst b/docs/developpers/index.rst
new file mode 100644
index 00000000..6a56edbe
--- /dev/null
+++ b/docs/developpers/index.rst
@@ -0,0 +1,15 @@
+Developpers documentation
+=========================
+
+This documentation is targeted primarily at developpers who want to understand
+how Funkwhale work and how to build apps that integrate with Funkwhale's ecosystem.
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 2
+
+   ../api
+   ../federation/index
+   subsonic
diff --git a/docs/developpers/subsonic.rst b/docs/developpers/subsonic.rst
new file mode 100644
index 00000000..df269e95
--- /dev/null
+++ b/docs/developpers/subsonic.rst
@@ -0,0 +1,70 @@
+Subsonic API
+============
+
+Funkwhale implements a subset of the `Subsonic API <http://www.subsonic.org/pages/api.jsp>`_ that makes it compatible
+with various apps in the Subsonic ecosystem (See :doc:`../users/apps`).
+
+Supported endpoints
+-------------------
+
+We seek the best compatibility with existing apps and wil eventually implement
+all endpoints that match Funkwhale's feature set. However, the current implementation
+do not include folder-based endpoints, as it does not match our internal model at all
+and will require substantial effort to emulate.
+
+We'll try to keep this list up-to-date, but you can also browse `the relevant code
+<https://code.eliotberriot.com/funkwhale/funkwhale/blob/develop/api/funkwhale_api/subsonic/views.py>`_
+if needed.
+
+As of today, the following endpoints are implemented:
+
+- createPlaylist
+- deletePlaylist
+- getAlbum
+- getAlbumList2
+- getArtist
+- getArtistInfo2
+- getArtists
+- getAvatar
+- getCoverArt
+- getIndexes
+- getLicense
+- getMusicFolders
+- getPlaylist
+- getPlaylists
+- getRandomSongs
+- getSong
+- getStarred
+- getStarred2
+- getUser
+- ping
+- scrobble
+- search3
+- star
+- stream
+- unstar
+- updatePlaylist
+
+We support both XML and JSON formats for all those endpoints.
+
+Additional properties
+---------------------
+
+Regardless of the endpoints, we always return those additional properties
+in our payload, which you can use to adapt your client behaviour if needed:
+
+.. code-block:: json
+
+    {
+        "subsonic-response": {
+            ...
+            "type": "funkwhale",
+            "funkwhaleVersion": "0.17"
+        }
+    }
+
+Testing a Subsonic app
+----------------------
+
+We maintain a demo server at https://demo.funkwhale.audio/, which you can use for
+your tests. Example with the ping endpoint: https://demo.funkwhale.audio/rest/ping.view?f=json
diff --git a/docs/index.rst b/docs/index.rst
index ef02db64..5eb505c3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,8 +19,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
    configuration
    troubleshooting
    importing-music
-   federation/index
-   api
+   developpers/index
    third-party
    contributing
    translators
-- 
GitLab