From 4aabcf8d57b35fa29ef58efeb3c9cadaa47b10ba Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Tue, 26 Mar 2019 11:40:53 +0100
Subject: [PATCH 01/12] Libraries endpoint documentation

---
 docs/swagger.yml | 218 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 193 insertions(+), 25 deletions(-)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index de809242d..c4b413414 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -1,3 +1,16 @@
+# Undocumented endpoints:
+#  /api/v1/settings
+#  /api/v1/activity
+#  /api/v1/uploads
+#  /api/v1/listen
+#  /api/v1/playlists
+#  /api/v1/playlist-tracks
+#  /api/v1/favorites
+#  /api/v1/search
+#  /api/v1/radios
+#  /api/v1/history
+#  /api/v1/users
+
 openapi: "3.0.0"
 info:
   description: "Documentation for [Funkwhale](https://funkwhale.audio) API. The API is **not** stable yet."
@@ -30,11 +43,21 @@ components:
 security:
   - jwt: []
 
+tags:
+  - name: Auth and security
+    description: Login, logout and authorization endpoints
+  - name: Library and metadata
+    description: Information and metadata about musical and audio entities (albums, tracks, artists, etc.)
+  - name: Uploads and audio content
+    description: Manipulation and uploading of audio files
+    externalDocs:
+      url: https://docs.funkwhale.audio/users/managing.html
+
 paths:
   /token/:
     post:
       tags:
-        - "auth"
+        - "Auth and security"
       description:
         Obtain a JWT token you can use for authenticating your next requests.
       security: []
@@ -61,7 +84,7 @@ paths:
     get:
       summary: List artists
       tags:
-        - "artists"
+        - "Library and metadata"
       parameters:
         - name: "q"
           in: "query"
@@ -106,7 +129,7 @@ paths:
         - $ref: "#/parameters/ObjectId"
 
       tags:
-        - "artists"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -127,8 +150,7 @@ paths:
         - $ref: "#/parameters/PageSize"
 
       tags:
-        - "artists"
-        - "libraries"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -145,7 +167,7 @@ paths:
     get:
       summary: List albums
       tags:
-        - "albums"
+        - "Library and metadata"
       parameters:
         - name: "q"
           in: "query"
@@ -198,7 +220,7 @@ paths:
         - $ref: "#/parameters/ObjectId"
 
       tags:
-        - "albums"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -220,8 +242,7 @@ paths:
         - $ref: "#/parameters/PageSize"
 
       tags:
-        - "albums"
-        - "libraries"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -238,7 +259,7 @@ paths:
     get:
       summary: List tracks
       tags:
-        - "tracks"
+        - "Library and metadata"
       parameters:
         - name: "q"
           in: "query"
@@ -302,12 +323,12 @@ paths:
                           $ref: "#/definitions/Track"
   /tracks/{id}/:
     get:
-      summary: Retrieve a single track
       parameters:
         - $ref: "#/parameters/ObjectId"
+      summary: Retrieve a single track
 
       tags:
-        - "tracks"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -329,8 +350,7 @@ paths:
         - $ref: "#/parameters/PageSize"
 
       tags:
-        - "tracks"
-        - "libraries"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -347,7 +367,7 @@ paths:
     get:
       summary: List licenses
       tags:
-        - "licenses"
+        - "Library and metadata"
       parameters:
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
@@ -366,19 +386,19 @@ paths:
                           $ref: "#/definitions/License"
 
   /licenses/{code}/:
+    parameters:
+      - name: code
+        in: path
+        description: License code
+        required: true
+        schema:
+          type: string
+          example: cc0-1.0
     get:
       summary: Retrieve a single license
-      parameters:
-        - name: code
-          in: path
-          description: License code
-          required: true
-          schema:
-            type: string
-            example: cc0-1.0
 
       tags:
-        - "licenses"
+        - "Library and metadata"
       responses:
         200:
           content:
@@ -391,6 +411,89 @@ paths:
               schema:
                 $ref: "#/definitions/ResourceNotFound"
 
+  /libraries/:
+    get:
+      summary: List owned libraries
+      tags:
+        - "Uploads and audio content"
+      parameters:
+        - $ref: "#/parameters/PageNumber"
+        - $ref: "#/parameters/PageSize"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/definitions/ResultPage"
+                  - type: "object"
+                    properties:
+                      results:
+                        type: "array"
+                        items:
+                          $ref: "#/definitions/OwnedLibrary"
+    post:
+      tags:
+        - "Uploads and audio content"
+      description:
+        Create a new library
+      security: []
+      responses:
+        201:
+          $ref: "#/responses/201"
+        400:
+          $ref: "#/responses/400"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/definitions/OwnedLibraryCreate"
+
+  /libraries/{uuid}/:
+    parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: "string"
+          format: "uuid"
+    get:
+      summary: Retrieve a library
+      tags:
+        - "Uploads and audio content"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/OwnedLibrary"
+    post:
+      summary: Update a library
+      tags:
+        - "Uploads and audio content"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/definitions/OwnedLibraryCreate"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/OwnedLibrary"
+    delete:
+      summary: Delete a library and all associated uploads
+      description: |
+        This will delete the library, all associated uploads, follows, and broadcast
+        the event on the federation.
+      tags:
+        - "Uploads and audio content"
+      responses:
+        204:
+          $ref: "#/responses/204"
 
 parameters:
   ObjectId:
@@ -434,11 +537,35 @@ parameters:
       required: false
       type: "boolean"
 
+responses:
+  201:
+    description: Successfully created
+  204:
+    description: Successfully deleted
+  400:
+    description: Bad request
+
 properties:
   mbid:
     type: "string"
-    formats: "uuid"
+    format: "uuid"
     description: "A musicbrainz ID"
+  creation_date:
+    type: "string"
+    format: "date-time"
+  privacy_level:
+    type: string
+    example: "me"
+    description: "'me' means private, 'instance' means viewable by local users, 'everyone' means public"
+    enum:
+      - "me"
+      - "instance"
+      - "everyone"
+  fid:
+    type: "string"
+    format: "uri"
+    description: "Federation ID"
+    example: "https://my.instance/federation/music/libraries/3fa85f64-5717-4562-b3fc-2c963f66afa6"
 
 definitions:
   ResultPage:
@@ -793,6 +920,47 @@ definitions:
         format: "uri"
         description: "URL to stream the upload"
 
+  OwnedLibraryCreate:
+    type: "object"
+    properties:
+      password:
+        type: "name"
+        example: "My new library"
+      description:
+        required: false
+        type: "string"
+        example: "Lots of interesting content"
+      privacy_level:
+        $ref: "#/properties/privacy_level"
+
+  OwnedLibrary:
+    type: "object"
+    properties:
+      uuid:
+        type: string
+        format: uuid
+      fid:
+        $ref: "#/properties/fid"
+      name:
+        type: "string"
+        example: "My Creative Commons library"
+      description:
+        type: "string"
+        example: "All content is under CC-BY"
+      creation_date:
+        $ref: "#/properties/creation_date"
+      privacy_level:
+        $ref: "#/properties/privacy_level"
+      uploads_count:
+        type: "integer"
+        format: "int64"
+        example: 34
+      size:
+        type: "integer"
+        format: "int64"
+        example: 678917000
+        description: "Total size of uploads in the library, in bytes"
+
   ResourceNotFound:
     type: "object"
     properties:

From 5b74448e665ab139b88ff1f73de5789951e2780f Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Tue, 26 Mar 2019 12:32:04 +0100
Subject: [PATCH 02/12] Documented /uploads endpoint

---
 docs/swagger.yml | 149 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 138 insertions(+), 11 deletions(-)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index c4b413414..45ca6246d 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -1,7 +1,6 @@
 # Undocumented endpoints:
 #  /api/v1/settings
 #  /api/v1/activity
-#  /api/v1/uploads
 #  /api/v1/listen
 #  /api/v1/playlists
 #  /api/v1/playlist-tracks
@@ -437,7 +436,6 @@ paths:
         - "Uploads and audio content"
       description:
         Create a new library
-      security: []
       responses:
         201:
           $ref: "#/responses/201"
@@ -495,6 +493,96 @@ paths:
         204:
           $ref: "#/responses/204"
 
+  /uploads/:
+    get:
+      summary: List owned uploads
+      tags:
+        - "Uploads and audio content"
+      parameters:
+        - name: "q"
+          in: "query"
+          default: null
+          description: "Search query used to filter uploads"
+          schema:
+            required: false
+            type: "string"
+            example: "Dire straits"
+        - $ref: "#/parameters/PageNumber"
+        - $ref: "#/parameters/PageSize"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/definitions/ResultPage"
+                  - type: "object"
+                    properties:
+                      results:
+                        type: "array"
+                        items:
+                          $ref: "#/definitions/OwnedUpload"
+    post:
+      tags:
+        - "Uploads and audio content"
+      description:
+        Upload a new file in a library. The event will be broadcasted on federation,
+        according to the library visibility and followers.
+      responses:
+        201:
+          $ref: "#/responses/201"
+        400:
+          $ref: "#/responses/400"
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                library:
+                  type: string
+                  format: uuid
+                  description: "The library in which the audio should be stored"
+                import_reference:
+                  type: string
+                  example: "Import launched via API client on 04/19"
+                source:
+                  type: string
+                  example: "upload://filename.mp3"
+                audio_file:
+                  type: string
+                  format: binary
+
+  /uploads/{uuid}/:
+    parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: "string"
+          format: "uuid"
+    get:
+      summary: Retrieve an upload
+      tags:
+        - "Uploads and audio content"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/OwnedUpload"
+    delete:
+      summary: Delete an upload
+      description: |
+        This will delete the upload from the server and broadcast the event
+        on the federation.
+      tags:
+        - "Uploads and audio content"
+      responses:
+        204:
+          $ref: "#/responses/204"
+
 parameters:
   ObjectId:
     name: id
@@ -556,7 +644,10 @@ properties:
   privacy_level:
     type: string
     example: "me"
-    description: "'me' means private, 'instance' means viewable by local users, 'everyone' means public"
+    description: >
+     * `me`: private
+     * `instance`: accessible by local users
+     * `everyone`: public (including over federation)
     enum:
       - "me"
       - "instance"
@@ -566,6 +657,27 @@ properties:
     format: "uri"
     description: "Federation ID"
     example: "https://my.instance/federation/music/libraries/3fa85f64-5717-4562-b3fc-2c963f66afa6"
+  audio_mimetype:
+    type: string
+    example: "audio/ogg"
+    enum:
+      - "audio/ogg"
+      - "audio/mpeg"
+      - "audio/x-flac"
+      - "audio/flac"
+  import_status:
+    type: string
+    example: "finished"
+    enum:
+      - "pending"
+      - "finished"
+      - "errored"
+      - "skipped"
+    description: >
+     * `pending`: waiting to be processed by the server
+     * `finished`: successfully processed by the server
+     * `errored`: couldn't be processed by the server (e.g because of a tagging issue)
+     * `skipped`: processed by the server but skipped, because considered as a duplicate of an existing upload
 
 definitions:
   ResultPage:
@@ -903,18 +1015,14 @@ definitions:
         example: 128000
         description: "Bitrate of the file, in bytes/s"
       mimetype:
-        type: string
-        example: "audio/ogg"
-        enum:
-          - "audio/ogg"
-          - "audio/mpeg"
-          - "audio/x-flac"
-          - "audio/flac"
+        $ref: "#/properties/audio_mimetype"
       extension:
         type: string
         example: "ogg"
         description: "File extension of the upload"
-
+      filename:
+        type: "string"
+        example: "Myfile.mp3"
       listen_url:
         type: "string"
         format: "uri"
@@ -961,6 +1069,25 @@ definitions:
         example: 678917000
         description: "Total size of uploads in the library, in bytes"
 
+  OwnedUpload:
+    type: "object"
+    allOf:
+      - $ref: "#/definitions/Upload"
+      - type: "object"
+        properties:
+          import_status:
+            $ref: "#/properties/import_status"
+          track:
+            $ref: "#/definitions/Track"
+          library:
+            $ref: "#/definitions/OwnedLibrary"
+          source:
+            type: "string"
+            example: "upload://myfile.mp3"
+          import_reference:
+            type: "string"
+            example: "Import launched via web UI on 03/18"
+
   ResourceNotFound:
     type: "object"
     properties:

From 800dd5ba182d99756518ca4c1bbf4af5b60d867b Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Tue, 26 Mar 2019 13:58:47 +0100
Subject: [PATCH 03/12] Documented /favorites endpoint

---
 docs/swagger.yml | 166 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 158 insertions(+), 8 deletions(-)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index 45ca6246d..94bf33c4f 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -4,7 +4,6 @@
 #  /api/v1/listen
 #  /api/v1/playlists
 #  /api/v1/playlist-tracks
-#  /api/v1/favorites
 #  /api/v1/search
 #  /api/v1/radios
 #  /api/v1/history
@@ -12,7 +11,15 @@
 
 openapi: "3.0.0"
 info:
-  description: "Documentation for [Funkwhale](https://funkwhale.audio) API. The API is **not** stable yet."
+  description: |
+    Interactive documentation for [Funkwhale](https://funkwhale.audio) API.
+
+    The API is **not** freezed yet, but we will document breaking changes in our changelog,
+    and try to avoid those as much as possible.
+
+    For more targeted guides regarding API usage, and especially authentication, please
+    refer to [https://docs.funkwhale.audio/api.html](https://docs.funkwhale.audio/api.html)
+
   version: "1.0.0"
   title: "Funkwhale API"
 
@@ -51,6 +58,8 @@ tags:
     description: Manipulation and uploading of audio files
     externalDocs:
       url: https://docs.funkwhale.audio/users/managing.html
+  - name: Content curation
+    description: Favorites, playlists, radios
 
 paths:
   /token/:
@@ -92,7 +101,6 @@ paths:
           schema:
             required: false
             type: "string"
-            example: "carpenter"
         - allOf:
             - $ref: "#/parameters/Ordering"
             - default: "-creation_date"
@@ -175,7 +183,6 @@ paths:
           schema:
             required: false
             type: "string"
-            example: "carpenter"
         - name: "artist"
           in: "query"
           default: null
@@ -267,7 +274,6 @@ paths:
           schema:
             required: false
             type: "string"
-            example: "carpenter"
         - name: "artist"
           in: "query"
           default: null
@@ -276,6 +282,13 @@ paths:
             required: false
             type: "integer"
             format: "int64"
+        - name: "favorites"
+          in: "query"
+          default: null
+          description: "filter/exclude tracks favorited by the current user"
+          schema:
+            required: false
+            type: "boolean"
         - name: "album"
           in: "query"
           default: null
@@ -477,7 +490,7 @@ paths:
             schema:
               $ref: "#/definitions/OwnedLibraryCreate"
       responses:
-        200:
+        201:
           content:
             application/json:
               schema:
@@ -583,6 +596,91 @@ paths:
         204:
           $ref: "#/responses/204"
 
+  /favorites/tracks/:
+    get:
+      tags:
+        - "Content curation"
+      parameters:
+        - name: "q"
+          in: "query"
+          default: null
+          description: "Search query used to filter favorites"
+          schema:
+            required: false
+            type: "string"
+        - name: "user"
+          in: "query"
+          default: null
+          description: "Limit results to favorites belonging to the given user"
+          schema:
+            $ref: "#/parameters/ObjectId"
+        - $ref: "#/parameters/PageNumber"
+        - $ref: "#/parameters/PageSize"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/definitions/ResultPage"
+                  - type: "object"
+                    properties:
+                      results:
+                        type: "array"
+                        items:
+                          $ref: "#/definitions/TrackFavorite"
+    post:
+      summary: Mark the given track as favorite
+      tags:
+        - "Content curation"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              properties:
+                track:
+                  type: "integer"
+                  format: "int64"
+                  example: 98
+      responses:
+        201:
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  id:
+                    type: "integer"
+                    format: "int64"
+                    example: 876
+                  track:
+                    type: "integer"
+                    format: "int64"
+                    example: 98
+                  creation_date:
+                    $ref: "#/properties/creation_date"
+  /favorites/tracks/remove/:
+    post:
+      summary: Remove the given track from favorites
+      tags:
+        - "Content curation"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              properties:
+                track:
+                  type: "integer"
+                  format: "int64"
+                  example: 98
+      responses:
+        204:
+          $ref: "#/responses/204"
+
 parameters:
   ObjectId:
     name: id
@@ -644,7 +742,7 @@ properties:
   privacy_level:
     type: string
     example: "me"
-    description: >
+    description: |
      * `me`: private
      * `instance`: accessible by local users
      * `everyone`: public (including over federation)
@@ -673,7 +771,7 @@ properties:
       - "finished"
       - "errored"
       - "skipped"
-    description: >
+    description: |
      * `pending`: waiting to be processed by the server
      * `finished`: successfully processed by the server
      * `errored`: couldn't be processed by the server (e.g because of a tagging issue)
@@ -1087,6 +1185,58 @@ definitions:
           import_reference:
             type: "string"
             example: "Import launched via web UI on 03/18"
+  TrackFavorite:
+    type: "object"
+    properties:
+      id:
+        type: "integer"
+        format: "int64"
+        example: 876
+      track:
+        $ref: "#/definitions/Track"
+      user:
+        $ref: "#/definitions/User"
+      creation_date:
+        $ref: "#/properties/creation_date"
+  User:
+    type: "object"
+    properties:
+      id:
+        type: "integer"
+        format: "int64"
+        example: 23
+      username:
+        type: "string"
+        example: "alice"
+      name:
+        type: "string"
+        example: "Alice Kingsley"
+      avatar:
+        $ref: "#/definitions/Avatar"
+
+  Avatar:
+    type: "object"
+    properties:
+      original:
+        type: "string"
+        format: "uri"
+        description: "Original image URL"
+        example: "http://yourinstance/media/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996.jpg"
+      square_crop:
+        type: "string"
+        format: "uri"
+        description: "400x400 thumbnail URL"
+        example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-400x400-70.jpg"
+      small_square_crop:
+        type: "string"
+        format: "uri"
+        description: "50x50 thumbnail URL"
+        example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-50x50-70.jpg"
+      medium_square_crop:
+        type: "string"
+        format: "uri"
+        description: "200x200 thumbnail URL"
+        example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-200x200-70.jpg"
 
   ResourceNotFound:
     type: "object"

From a1817f6473341cfa9c455cecde4539ce9141db9f Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Tue, 26 Mar 2019 15:01:00 +0100
Subject: [PATCH 04/12] Documented /listen endpoint

---
 docs/swagger.yml | 66 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index 94bf33c4f..4ef60de6f 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -1,7 +1,6 @@
 # Undocumented endpoints:
 #  /api/v1/settings
 #  /api/v1/activity
-#  /api/v1/listen
 #  /api/v1/playlists
 #  /api/v1/playlist-tracks
 #  /api/v1/search
@@ -374,7 +373,66 @@ paths:
             application/json:
               schema:
                 $ref: "#/definitions/ResourceNotFound"
+  /listen/{uuid}/:
+    get:
+      summary: Download the audio file matching the given track uuid
+      description: |
+        Given a track uuid (and not ID), return the first found audio file
+        accessible by the user making the request.
 
+        In case of a remote upload, this endpoint will fetch the audio file from the remote
+        and cache it before sending the response.
+
+      parameters:
+        - name: uuid
+          in: path
+          required: true
+          description: Track uuid
+          schema:
+            type: "string"
+            format: "uuid"
+        - name: to
+          in: query
+          required: false
+          description: |
+            If specified, the endpoint will return a transcoded version of the original
+            audio file.
+
+            Since transcoding happens on the fly, it can significantly increase response time,
+            and it's recommended to request transcoding only for files that are not playable
+            by the client.
+
+            This endpoint support bytess-range requests.
+          schema:
+            $ref: "#/properties/transcode_options"
+        - name: upload
+          in: query
+          required: false
+          summary: An upload uuid
+          description: |
+            If specified, will return the audio for the given upload uuid.
+
+            This is useful for tracks that have multiple uploads available.
+
+          schema:
+            type: string
+            format: uuid
+
+      tags:
+        - "Library and metadata"
+      responses:
+        200:
+          content:
+            '*/*':
+              description: "Audio file, as binary data"
+              schema:
+                type: string
+                format: binary
+        404:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/ResourceNotFound"
   /licenses/:
     get:
       summary: List licenses
@@ -777,6 +835,12 @@ properties:
      * `errored`: couldn't be processed by the server (e.g because of a tagging issue)
      * `skipped`: processed by the server but skipped, because considered as a duplicate of an existing upload
 
+  transcode_options:
+    type: string
+    enum:
+      - "ogg"
+      - "mp3"
+
 definitions:
   ResultPage:
     type: "object"

From dcb9ca04a13f33ff7ceb440b2dfc2d476c080774 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Tue, 26 Mar 2019 15:38:14 +0100
Subject: [PATCH 05/12] Documented /users and /auth endpoints

---
 docs/swagger.yml | 160 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 159 insertions(+), 1 deletion(-)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index 4ef60de6f..4a1327e94 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -6,7 +6,6 @@
 #  /api/v1/search
 #  /api/v1/radios
 #  /api/v1/history
-#  /api/v1/users
 
 openapi: "3.0.0"
 info:
@@ -65,6 +64,7 @@ paths:
     post:
       tags:
         - "Auth and security"
+      summary: Get an API token
       description:
         Obtain a JWT token you can use for authenticating your next requests.
       security: []
@@ -87,6 +87,78 @@ paths:
                   type: "string"
                   example: "demo"
 
+  /auth/registration/:
+    post:
+      summary: Create an account
+      description: |
+        Register a new account on this instance. An invitation code will be required
+        if sign up is disabled.
+      tags:
+        - "Auth and security"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              properties:
+                username:
+                  type: "string"
+                  example: "alice"
+                email:
+                  type: "string"
+                  format: "email"
+                invitation:
+                  type: "string"
+                  example: "INVITECODE"
+                  required: false
+                  description: An invitation code, required if signups are closed on the instance.
+                password1:
+                  type: "string"
+                  example: "passw0rd"
+                password2:
+                  type: "string"
+                  description: Must be identical to password1
+                  example: "passw0rd"
+      responses:
+        201:
+          $ref: "#/responses/201"
+  /auth/password/reset/:
+    post:
+      summary: Request a password reset
+      description: |
+        Request a password reset. An email with reset instructions will be sent to the provided email,
+        if it's associated with a user account.
+      tags:
+        - "Auth and security"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              properties:
+                email:
+                  type: "string"
+                  format: "email"
+      responses:
+        200:
+          $ref: "#/responses/200"
+  /users/users/me/:
+    get:
+      summary: Retrive profile information
+      description: |
+        Retrieve profile informations of the current user
+      tags:
+        - "Auth and security"
+
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/Me"
+
   /artists/:
     get:
       summary: List artists
@@ -782,6 +854,8 @@ parameters:
       type: "boolean"
 
 responses:
+  200:
+    description: Success
   201:
     description: Successfully created
   204:
@@ -1278,6 +1352,37 @@ definitions:
       avatar:
         $ref: "#/definitions/Avatar"
 
+  Me:
+    type: "object"
+    allOf:
+      - $ref: "#/definitions/User"
+      - type: "object"
+        properties:
+          full_username:
+            type: "string"
+            description: Full username, for use on federation
+            example: "alice@yourdomain.com"
+          email:
+            type: "string"
+            format: "email"
+            description: Email address associated with the account
+            example: "alice@email.provider"
+          is_staff:
+            type: "boolean"
+            example: false
+          is_superuser:
+            type: "boolean"
+            example: false
+          date_joined:
+            type: "string"
+            format: "date-time"
+          privacy_level:
+            $ref: "#/properties/privacy_level"
+            description: Default privacy-level associated with the user account
+          quota_status:
+            $ref: "#/definitions/QuotaStatus"
+          permissions:
+            $ref: "#/definitions/Permissions"
   Avatar:
     type: "object"
     properties:
@@ -1301,6 +1406,59 @@ definitions:
         format: "uri"
         description: "200x200 thumbnail URL"
         example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-200x200-70.jpg"
+  QuotaStatus:
+    type: "object"
+    properties:
+      max:
+        type: "integer"
+        format: "int64"
+        description: Storage space allocated to this user, in MB
+        example: 5000
+      remaining:
+        type: "integer"
+        format: "int64"
+        description: Remaining storage space for this user, in MB
+        example: 4600
+      current:
+        type: "integer"
+        format: "int64"
+        description: Storage space used by this user, in MB
+        example: 400
+      skipped:
+        type: "integer"
+        format: "int64"
+        description: Storage space occupied by uploads with "skipped" import status, in MB
+        example: 30
+      finished:
+        type: "integer"
+        format: "int64"
+        description: Storage space occupied by uploads with "finished" import status, in MB
+        example: 350
+      pending:
+        type: "integer"
+        format: "int64"
+        description: Storage space occupied by uploads with "pending" import status, in MB
+        example: 15
+      errored:
+        type: "integer"
+        format: "int64"
+        description: Storage space occupied by uploads with "errored" import status, in MB
+        example: 5
+  Permissions:
+    type: "object"
+    properties:
+      library:
+        type: "boolean"
+        example: false
+        description: A boolean indicating if the user can manage the instance library
+      moderation:
+        type: "boolean"
+        example: false
+        description: A boolean indicating if the user has moderation permission
+      settings:
+        type: "boolean"
+        example: false
+        description: A boolean indicating if the user can manage instance settings and users
 
   ResourceNotFound:
     type: "object"

From 659c355ad849608e1f8b410b5caefffaee36b3f6 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Tue, 26 Mar 2019 17:21:44 +0100
Subject: [PATCH 06/12] API doc introduction

---
 docs/swagger.yml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index 4a1327e94..d83171698 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -15,6 +15,27 @@ info:
     The API is **not** freezed yet, but we will document breaking changes in our changelog,
     and try to avoid those as much as possible.
 
+    Usage
+    -----
+
+    Click on an endpoint name to inspect its properties, parameters and responses.
+
+    Use the "Try it out" button to send a real world payload to the endpoint and inspect
+    the corresponding response.
+
+    Authentication
+    --------------
+
+    To authenticate, use the `/token/` endpoint with a username and password, and copy/paste
+    the resulting JWT token in the `Authorize` modal. All subsequent requests made via the interactive
+    documentation will be authenticated.
+
+    If you keep the default server (https://demo.funkwhale.audio), the default username and password
+    couple is "demo" and "demo".
+
+    Resources
+    ---------
+
     For more targeted guides regarding API usage, and especially authentication, please
     refer to [https://docs.funkwhale.audio/api.html](https://docs.funkwhale.audio/api.html)
 

From 537f18cf08666c5c2cd3cc8d8469eef36f1915c5 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Mon, 1 Apr 2019 09:45:54 +0200
Subject: [PATCH 07/12] Added missing library_id parameter on in-place import
 documentation

---
 docs/admin/importing-music.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/admin/importing-music.rst b/docs/admin/importing-music.rst
index 1677d919b..acf025c6c 100644
--- a/docs/admin/importing-music.rst
+++ b/docs/admin/importing-music.rst
@@ -100,8 +100,9 @@ you can create a symlink like this::
     ln -s /media/mynfsshare /srv/funkwhale/data/music/nfsshare
 
 And import music from this share with this command::
-
-    python api/manage.py import_files "/srv/funkwhale/data/music/nfsshare/**/*.ogg" --recursive --noinput --in-place
+    
+    export LIBRARY_ID="<your_libary_id>"
+    python api/manage.py import_files $LIBRARY_ID "/srv/funkwhale/data/music/nfsshare/**/*.ogg" --recursive --noinput --in-place
 
 On docker setups, it will require a bit more work, because while the ``/srv/funkwhale/data/music`` is mounted
 in containers, symlinked directories are not. To fix that, in your ``docker-compose.yml`` file, ensure each symlinked

From cf51d37a474dcf50b352a676436dc32b05426817 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Mon, 1 Apr 2019 11:36:13 +0200
Subject: [PATCH 08/12] Added a small json file in documentation to get
 releases info

---
 docs/build_docs.sh        |  2 +-
 docs/get-releases-json.py | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 docs/get-releases-json.py

diff --git a/docs/build_docs.sh b/docs/build_docs.sh
index fbf2036af..c2468db21 100755
--- a/docs/build_docs.sh
+++ b/docs/build_docs.sh
@@ -1,5 +1,5 @@
 #!/bin/bash -eux
 # Building sphinx and swagger docs
-
 python -m sphinx . $BUILD_PATH
 TARGET_PATH="$BUILD_PATH/swagger" ./build_swagger.sh
+python ./get-releases-json.py > $BUILD_PATH/releases.json
diff --git a/docs/get-releases-json.py b/docs/get-releases-json.py
new file mode 100644
index 000000000..8f623e7a0
--- /dev/null
+++ b/docs/get-releases-json.py
@@ -0,0 +1,34 @@
+import json
+import subprocess
+
+from distutils.version import StrictVersion
+
+
+def get_versions():
+
+    output = subprocess.check_output(
+        ["git", "tag", "-l", "--format=%(creatordate:iso-strict)|%(refname:short)"]
+    )
+    tags = []
+
+    for line in output.decode().splitlines():
+        try:
+            date, tag = line.split("|")
+        except (ValueError):
+            continue
+
+        if not date or not tag:
+            continue
+
+        tags.append({"id": tag, "date": date})
+    return sorted(tags, key=lambda tag: StrictVersion(tag["id"]), reverse=True)
+
+
+def main():
+    versions = get_versions()
+    data = {"count": len(versions), "releases": versions}
+    print(json.dumps(data))
+
+
+if __name__ == "__main__":
+    main()

From 3a4c9278204e53f758a7cb1efc639875c40035c1 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Mon, 1 Apr 2019 19:20:17 +0200
Subject: [PATCH 09/12] Added missing sudo in upgrade instructions

---
 docs/admin/upgrading.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/admin/upgrading.rst b/docs/admin/upgrading.rst
index 9a33836cc..5b222ce49 100644
--- a/docs/admin/upgrading.rst
+++ b/docs/admin/upgrading.rst
@@ -164,7 +164,7 @@ match what is described in :doc:`/installation/debian`:
     # download more recent API files
     sudo -u funkwhale curl -L -o "api-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_api"
     sudo -u funkwhale unzip "api-$FUNKWHALE_VERSION.zip" -d extracted
-    sudo -u funkwhale rm -rf api/ && mv extracted/api .
+    sudo -u funkwhale rm -rf api/ && sudo -u funkwhale mv extracted/api .
     sudo -u funkwhale rm -rf extracted
 
     # update os dependencies

From da6b3400a028461cfa38021355d0ea3e5bfb4dab Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Fri, 5 Apr 2019 17:48:04 +0200
Subject: [PATCH 10/12] Better permissions on .env file, added a few missing
 env vars in mono-container install

---
 docs/installation/debian.rst | 4 +++-
 docs/installation/docker.rst | 7 +++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/installation/debian.rst b/docs/installation/debian.rst
index e8780fe8e..06449cf7f 100644
--- a/docs/installation/debian.rst
+++ b/docs/installation/debian.rst
@@ -199,6 +199,7 @@ Download the sample environment file:
 
         cp /srv/funkwhale/deploy/env.prod.sample /srv/funkwhale/config/.env
 
+
 Generate a secret key for Django::
 
     openssl rand -base64 45
@@ -208,7 +209,8 @@ configuration options are mentioned at the top of the file.
 
 .. code-block:: shell
 
-    nano /srv/funkwhale/api/.env
+    chmod 600 /srv/funkwhale/config/.env  # reduce permissions on the .env file since it contains sensitive data
+    nano /srv/funkwhale/config/.env
 
 Paste the secret key you generated earlier at the entry
 ``DJANGO_SECRET_KEY`` and populate the ``DATABASE_URL``
diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst
index b6f67f5e4..f227ace61 100644
--- a/docs/installation/docker.rst
+++ b/docs/installation/docker.rst
@@ -52,10 +52,15 @@ Create an env file to store a few important configuration options:
     touch .env
     echo "FUNKWHALE_HOSTNAME=yourdomain.funkwhale" >> .env
     echo "FUNKWHALE_PROTOCOL=https" >> .env  # or http
+    echo "NGINX_MAX_BODY_SIZE=100M" >> .env
+    echo "FUNKWHALE_API_IP=127.0.0.1" >> .env
+    echo "FUNKWHALE_API_PORT=5000" >> .env  # or the container port you want to expose on the host
     echo "DJANGO_SECRET_KEY=$(openssl rand -hex 45)" >> .env  # generate and store a secure secret key for your instance
     # Remove this if you expose the container directly on ports 80/443
     echo "NESTED_PROXY=1" >> .env
 
+    chmod 600 .env  # reduce permissions on the .env file since it contains sensitive data
+
 Then start the container:
 
 .. code-block:: shell
@@ -179,8 +184,10 @@ Create your env file:
 
     curl -L -o .env "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/|version|/deploy/env.prod.sample"
     sed -i "s/FUNKWHALE_VERSION=latest/FUNKWHALE_VERSION=$FUNKWHALE_VERSION/" .env
+    chmod 600 .env  # reduce permissions on the .env file since it contains sensitive data
     sudo nano .env
 
+
 Ensure to edit it to match your needs (this file is heavily commented), in particular ``DJANGO_SECRET_KEY`` and ``FUNKWHALE_HOSTNAME``.
 You should take a look at the `configuration reference <https://docs.funkwhale.audio/configuration.html#configuration-reference>`_ for more detailed information regarding each setting.
 

From e9cfc4d27994e2fa3189ed209b0b48a5de50696e Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Mon, 8 Apr 2019 11:11:35 +0200
Subject: [PATCH 11/12] Fixed some typo/wording in the documentation

---
 docs/developers/architecture.rst | 4 ++--
 docs/users/create.rst            | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/developers/architecture.rst b/docs/developers/architecture.rst
index 9ea5ab48e..e1f66bad9 100644
--- a/docs/developers/architecture.rst
+++ b/docs/developers/architecture.rst
@@ -59,10 +59,10 @@ The reverse proxy
 
 Funkwhale's API server should never be exposed directly to the internet, as we require
 a reverse proxy (Apache or Nginx) for performance and security reasons. The reverse proxy
-will receive client HTTP requests, and:
+will receive client HTTP or HTTPS requests, and:
 
 - Proxy them to the API server
-- Serve requested static files (Audio files, stylesheets, javascript, fonts...)
+- Serve requested static files (audio files, stylesheets, javascript, fonts...)
 
 The API server
 --------------
diff --git a/docs/users/create.rst b/docs/users/create.rst
index 47c721f1f..c185f4b24 100644
--- a/docs/users/create.rst
+++ b/docs/users/create.rst
@@ -2,10 +2,10 @@ Creating a Funkwhale Account
 ============================
 
 Before you can start using Funkwhale, you will need to set up an account on an instance. While
-some instances allow you to listen to public music anonymously, you will need to create account
+some instances allow you to listen to public music anonymously, you will need to create an account
 to benefit from the full Funkwhale experience.
 
-A list of instances along with other useful information such as version and enabled features can be found
+A list of instances along with other useful informations such as version and enabled features can be found
 `here <https://network.funkwhale.audio/dashboards/d/overview/network-overview>`_. Servers marked with
 "Open registrations" are available to sign up to.
 

From ef6342f46d481f8229687198551da3dfb4a09936 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Thu, 16 May 2019 10:01:27 +0200
Subject: [PATCH 12/12] Fixed missing api/v1 prefix in swagger documentation

---
 docs/swagger.yml | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/swagger.yml b/docs/swagger.yml
index 47fd8d4b5..2e3bf9245 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -175,7 +175,7 @@ paths:
                   type: "string"
                   example: "demo"
 
-  /auth/registration/:
+  /api/v1/auth/registration/:
     post:
       summary: Create an account
       description: |
@@ -211,7 +211,7 @@ paths:
       responses:
         201:
           $ref: "#/responses/201"
-  /auth/password/reset/:
+  /api/v1/auth/password/reset/:
     post:
       summary: Request a password reset
       description: |
@@ -232,7 +232,7 @@ paths:
       responses:
         200:
           $ref: "#/responses/200"
-  /users/users/me/:
+  /api/v1/users/users/me/:
     get:
       summary: Retrive profile information
       description: |
@@ -560,7 +560,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/definitions/ResourceNotFound"
-  /listen/{uuid}/:
+  /api/v1/listen/{uuid}/:
     get:
       summary: Download the audio file matching the given track uuid
       description: |
@@ -675,7 +675,7 @@ paths:
               schema:
                 $ref: "#/definitions/ResourceNotFound"
 
-  /libraries/:
+  /api/v1/libraries/:
     get:
       summary: List owned libraries
       tags:
@@ -713,7 +713,7 @@ paths:
             schema:
               $ref: "#/definitions/OwnedLibraryCreate"
 
-  /libraries/{uuid}/:
+  /api/v1/libraries/{uuid}/:
     parameters:
       - name: uuid
         in: path
@@ -758,7 +758,7 @@ paths:
         204:
           $ref: "#/responses/204"
 
-  /uploads/:
+  /api/v1/uploads/:
     get:
       summary: List owned uploads
       tags:
@@ -819,7 +819,7 @@ paths:
                   type: string
                   format: binary
 
-  /uploads/{uuid}/:
+  /api/v1/uploads/{uuid}/:
     parameters:
       - name: uuid
         in: path
@@ -848,7 +848,7 @@ paths:
         204:
           $ref: "#/responses/204"
 
-  /favorites/tracks/:
+  /api/v1/favorites/tracks/:
     get:
       tags:
         - "Content curation"
@@ -913,7 +913,7 @@ paths:
                     example: 98
                   creation_date:
                     $ref: "#/properties/creation_date"
-  /favorites/tracks/remove/:
+  /api/v1/favorites/tracks/remove/:
     post:
       summary: Remove the given track from favorites
       tags: