From 4db0b9b42127d2905455e9b63419d21232de8dc7 Mon Sep 17 00:00:00 2001
From: Agate <me@agate.blue>
Date: Mon, 15 Jun 2020 09:10:41 +0200
Subject: [PATCH] Channels api docs

---
 api/funkwhale_api/favorites/filters.py |   1 +
 dev.yml                                |   2 +-
 docs/swagger.yml                       | 432 +++++++++++++++++++++----
 3 files changed, 370 insertions(+), 65 deletions(-)

diff --git a/api/funkwhale_api/favorites/filters.py b/api/funkwhale_api/favorites/filters.py
index 8a4b91bb2..b4dad93ac 100644
--- a/api/funkwhale_api/favorites/filters.py
+++ b/api/funkwhale_api/favorites/filters.py
@@ -13,6 +13,7 @@ class TrackFavoriteFilter(moderation_filters.HiddenContentFilterSet):
 
     class Meta:
         model = models.TrackFavorite
+        # XXX: 1.0 remove the user filter, we have scope=me now
         fields = ["user", "q", "scope"]
         hidden_content_fields_mapping = moderation_filters.USER_FILTER_CONFIG[
             "TRACK_FAVORITE"
diff --git a/dev.yml b/dev.yml
index 7ae73a51a..c22689304 100644
--- a/dev.yml
+++ b/dev.yml
@@ -154,7 +154,7 @@ services:
       - "8001:8001"
 
   api-docs:
-    image: swaggerapi/swagger-ui:v3.25
+    image: swaggerapi/swagger-ui:v3.26.0
     environment:
       - "API_URL=/swagger.yml"
     ports:
diff --git a/docs/swagger.yml b/docs/swagger.yml
index 2d160f45c..a9ecdd021 100644
--- a/docs/swagger.yml
+++ b/docs/swagger.yml
@@ -26,12 +26,9 @@ info:
     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.
+    To authenticate, use OAuth. You can register your own app using the `/apps` endpoint and proceed to the OAuth flow afterwards.
 
-    If you keep the default server (https://demo.funkwhale.audio), the default username and password
-    couple is "demo" and "demo".
+    You can use our demo server at `https://demo.funkwhale.audio` for testing purposes.
 
     Rate limiting
     -------------
@@ -183,6 +180,10 @@ tags:
     description: Manipulation and uploading of audio files
     externalDocs:
       url: https://docs.funkwhale.audio/users/managing.html
+  - name: Channels and subscriptions
+    description: Channel management and subscription
+    externalDocs:
+      url: https://docs.funkwhale.audio/users/upload.html#using-a-channel
   - name: Content curation
     description: Favorites, playlists, radios
   - name: Other
@@ -344,13 +345,8 @@ paths:
         - oauth2:
           - "read:libraries"
       parameters:
-        - name: "q"
-          in: "query"
-          default: null
-          description: "Search query used to filter artists"
-          schema:
-            required: false
-            type: "string"
+
+        - $ref: "#/parameters/Search"
         - allOf:
             - $ref: "#/parameters/Ordering"
             - default: "-creation_date"
@@ -365,6 +361,7 @@ paths:
         - $ref: "#/parameters/Playable"
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
+        - $ref: "#/parameters/Scope"
 
       responses:
         200:
@@ -436,13 +433,8 @@ paths:
         - oauth2:
           - "read:libraries"
       parameters:
-        - name: "q"
-          in: "query"
-          default: null
-          description: "Search query used to filter albums"
-          schema:
-            required: false
-            type: "string"
+
+        - $ref: "#/parameters/Search"
         - name: "artist"
           in: "query"
           default: null
@@ -465,6 +457,7 @@ paths:
         - $ref: "#/parameters/Playable"
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
+        - $ref: "#/parameters/Scope"
 
       responses:
         200:
@@ -538,13 +531,8 @@ paths:
         - oauth2:
           - "read:libraries"
       parameters:
-        - name: "q"
-          in: "query"
-          default: null
-          description: "Search query used to filter tracks"
-          schema:
-            required: false
-            type: "string"
+
+        - $ref: "#/parameters/Search"
         - name: "artist"
           in: "query"
           default: null
@@ -590,6 +578,7 @@ paths:
         - $ref: "#/parameters/Playable"
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
+        - $ref: "#/parameters/Scope"
 
       responses:
         200:
@@ -774,6 +763,8 @@ paths:
       parameters:
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
+        - $ref: "#/parameters/Search"
+        - $ref: "#/parameters/Scope"
       responses:
         200:
           content:
@@ -853,11 +844,17 @@ paths:
     get:
       summary: List channels
       tags:
-        - "Uploads and audio content"
+        - "Channels and subscriptions"
       parameters:
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
         - $ref: "#/parameters/Scope"
+        - $ref: "#/parameters/Search"
+        - $ref: "#/parameters/Tags"
+        - $ref: "#/parameters/Subscribed"
+        - $ref: "#/parameters/External"
+        - $ref: "#/parameters/ChannelOrdering"
+
       responses:
         200:
           content:
@@ -874,7 +871,7 @@ paths:
     post:
       summary: Create a new channel
       tags:
-        - "Uploads and audio content"
+        - "Channels and subscriptions"
       responses:
         201:
           $ref: "#/responses/201"
@@ -887,6 +884,53 @@ paths:
             schema:
               $ref: "#/definitions/ChannelCreate"
 
+  /api/v1/channels/metadata-choices:
+    summary: List metadata (locales, itunes categories) for creating and editing channels.
+    tags:
+      - "Channels and subscriptions"
+    get:
+      summary: List channels metadata options
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  language:
+                    type: "array"
+                    items:
+                      type: object
+                      properties:
+                        value:
+                          type: string
+                          description: ID of the locale in ISO 639 format
+                          example: "en"
+                        language:
+                          type: string
+                          example: "English"
+                  itunes_category:
+                    type: "array"
+                    items:
+                      type: object
+                      properties:
+                        value:
+                          type: string
+                          description: ID of the category
+                          example: "Business"
+                        label:
+                          type: string
+                          description: Readable label of the category
+                          example: "Business"
+                        children:
+                          type: array
+                          description: Some categories have subcategories
+                          items:
+                            type: string
+                            example: "Entrepreneurship"
+
   /api/v1/channels/{uuid}/:
     parameters:
       - name: uuid
@@ -898,7 +942,7 @@ paths:
     get:
       summary: Retrieve a channel
       tags:
-        - "Uploads and audio content"
+        - "Channels and subscriptions"
       responses:
         200:
           content:
@@ -908,7 +952,7 @@ paths:
     post:
       summary: Update a channel
       tags:
-        - "Uploads and audio content"
+        - "Channels and subscriptions"
       requestBody:
         required: true
         content:
@@ -927,27 +971,97 @@ paths:
         This will delete the channel, all associated uploads, follows, and broadcast
         the event on the federation.
       tags:
-        - "Uploads and audio content"
+        - "Channels and subscriptions"
       responses:
         204:
           $ref: "#/responses/204"
 
+  /api/v1/channels/rss-suscribe/:
+    post:
+      summary: Subscribe to a third-party podcast via its RSS feed
+
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              properties:
+                url:
+                  type: "string"
+                  description: URL of the RSS feed
+
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        201:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/Subscription"
+
+  /api/v1/channels/{uuid}/rss/:
+    parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: "string"
+          format: "uuid"
+    get:
+      summary: Get the RSS feed of a podcast channel. Only available for channel hosted on the pod where the API is queried.
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        200:
+          content:
+            application/rss+xml:
+
+  /api/v1/channels/{uuid}/subscribe/:
+    parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: "string"
+          format: "uuid"
+    post:
+      summary: Subscribe to the given channel
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        201:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/Subscription"
+
+  /api/v1/channels/{uuid}/unsubscribe/:
+    parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: "string"
+          format: "uuid"
+    post:
+      summary: Unsubscribe from the given channel
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        204:
+
   /api/v1/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/Search"
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
+        - $ref: "#/parameters/Scope"
       responses:
         200:
           content:
@@ -1004,6 +1118,61 @@ paths:
                   $ref: "#/definitions/ImportMetadata"
 
 
+  /api/v1/subscriptions/{uuid}/:
+    parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: "string"
+          format: "uuid"
+    get:
+      summary: Retrieve a subscription
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/Subscription"
+
+  /api/v1/subscriptions/:
+    get:
+      summary: List subscriptions
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/definitions/ResultPage"
+                  - type: "object"
+                    properties:
+                      results:
+                        type: "array"
+                        items:
+                          $ref: "#/definitions/Subscription"
+
+  /api/v1/subscriptions/all/:
+    get:
+      summary: Retrieve all subscriptions in a lightweight format, without pagination
+      tags:
+        - "Channels and subscriptions"
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  results:
+                    type: "array"
+                    items:
+                      $ref: "#/definitions/SubscriptionsAll"
+
   /api/v1/uploads/{uuid}/:
     parameters:
       - name: uuid
@@ -1076,21 +1245,11 @@ paths:
       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/Search"
         - $ref: "#/parameters/PageNumber"
         - $ref: "#/parameters/PageSize"
+        - $ref: "#/parameters/Scope"
+
       responses:
         200:
           content:
@@ -1205,6 +1364,28 @@ paths:
           $ref: "#/responses/204"
 
 parameters:
+
+  ChannelOrdering:
+    - $ref: "#/parameters/Ordering"
+    - default: "-creation_date"
+      schema:
+        required: false
+        type: "string"
+        example: "-creation_date"
+        enum:
+          - creation_date
+          - artist__modification_date
+
+  External:
+    name: "external"
+    in: "query"
+    default: null
+    description: "Filter/exclude channels created from a third-party, non-Funkwhale RSS feed"
+    schema:
+      required: false
+      type: "boolean"
+
+
   ObjectId:
     name: id
     in: path
@@ -1258,13 +1439,51 @@ parameters:
     name: "scope"
     in: "query"
     default: "all"
-    description: "Limit the results relative to the user making the request. `me` restrict to owned objects, `all` applies no restriction."
+    description: |
+      Limit the results to a given user or pod:
+        - Use `all` (or do not specify the property to disable scope filtering)
+        - Use `me` to retrieve content relative to the current user
+        - Use `actor:alice@example.com` to retrieve content relative to the account `alice@example.com
+        - Use `domain:example.com` to retrieve content relative to the domain `example.com
     schema:
       required: false
       type: "string"
       enum:
       - "me"
       - "all"
+      - "actor:alice@example.com"
+      - "domain:example.com"
+
+  Search:
+    name: "q"
+    in: "query"
+    default: "all"
+    description: "Limit the results to the corresponding search query"
+    schema:
+      required: false
+      type: "string"
+      example: "Bonobo"
+
+  Subscribed:
+    name: "subscribed"
+    in: "query"
+    description: "Limit or exclude results with a matching subsription from the current user"
+    schema:
+      required: false
+      type: boolean
+
+  Tags:
+    name: "tag"
+    in: "query"
+    description: "Limit the results to the corresponding tags. May be used multiple times, to retrieve objects matching al provided tags"
+    schema:
+      required: false
+      type: array
+      collectionFormat: csv
+      example:
+        - rock
+        - metal
+
 responses:
   200:
     description: Success
@@ -1276,6 +1495,26 @@ responses:
     description: Bad request
 
 properties:
+  description:
+    type: object
+    description: Text content associated with another resource, like and artist or channel.
+    properties:
+      text:
+        type: string
+        example: "This is **me**"
+        description: "The raw user input"
+      content_type:
+        type: string
+        enum:
+          - text/markdown
+          - text/plain
+          - text/html
+        description: "The raw user input"
+      html:
+        type: string
+        description: "HTML output based on user input"
+        readOnly: true
+
   mbid:
     type: "string"
     format: "uuid"
@@ -1342,6 +1581,16 @@ properties:
       type: string
       example: "Rock"
 
+  content_category:
+    type: "string"
+    description: Used to what kind of content is published in a chanel
+    enum:
+     - music
+     - podcast
+     - other
+
+
+
 definitions:
   OAuthApplication:
     type: "object"
@@ -1557,6 +1806,30 @@ definitions:
             format: "int64"
             example: 16
 
+  ChannelMetadata:
+    type: "object"
+    properties:
+      itunes_category:
+        type: string
+        example: Comedy
+        description: Itunes category (see `/api/v1/channels/metadata-choices`) for allowed values
+      itunes_subcategory:
+        type: string
+        example: Improv
+        description: Itunes subcategory (see `/api/v1/channels/metadata-choices`) for allowed values
+      language:
+        type: string
+        example: en
+        description: Language of the content, in ISO 639 format (see `/api/v1/channels/metadata-choices`) for allowed values
+      owner_name:
+        type: string
+        example: "Alice"
+        description: Used to make the channel compatible with other platforms (iTunes, Spotify, etc.)
+      owner_email:
+        type: string
+        example: "alice@example.com"
+        description: Used to make the channel compatible with other platforms (iTunes, Spotify, etc.)
+
   ChannelCreate:
     type: "object"
     properties:
@@ -1568,14 +1841,17 @@ definitions:
         type: "string"
         example: "aliceandbob"
         description: "The username to associate with the channel, for use over federation. This cannot be changed afterwards."
-      summary:
-        required: false
-        type: "string"
-        example: "A short, public description for the channel"
-        maxLength: 500
+      description:
+        $ref: "#/properties/description"
       tags:
         $ref: "#/properties/tags"
-
+      content_category:
+        $ref: "#/properties/content_category"
+      cover:
+        type: string
+        format: uuid
+      metadata:
+        $ref: "#/definitions/ChannelMetadata"
   ChannelUpdate:
     type: "object"
     properties:
@@ -1583,13 +1859,15 @@ definitions:
         type: "string"
         example: "A short, public name for the channel"
         maxLength: 255
-      summary:
-        required: false
-        type: "string"
-        example: "A short, public description for the channel"
-        maxLength: 500
+      description:
+        $ref: "#/properties/description"
       tags:
         $ref: "#/properties/tags"
+      cover:
+        type: string
+        format: uuid
+      metadata:
+        $ref: "#/definitions/ChannelMetadata"
 
   Channel:
     type: "object"
@@ -1607,6 +1885,32 @@ definitions:
       actor:
         $ref: "#/definitions/Actor"
         description: Actor representing the channel over federation
+
+  Subscription:
+    type: "object"
+    properties:
+      approved:
+        type: "string"
+      fid:
+        $ref: "#/properties/fid"
+      uuid:
+        type: "string"
+        format: "uuid"
+      creation_date:
+        $ref: "#/properties/creation_date"
+      channel:
+        $ref: "#/definitions/Channel"
+
+  SubscriptionsAll:
+    type: "object"
+    properties:
+      uuid:
+        type: "string"
+        format: "uuid"
+      channel:
+        type: "string"
+        format: "uuid"
+
   Library:
     type: "object"
     properties: