Commit 507041c7 authored by Agate's avatar Agate 💬
Browse files

Merge branch 'channels-api-docs' into 'master'

Channels api docs

See merge request !1146
parents 5de006b9 4db0b9b4
...@@ -13,6 +13,7 @@ class TrackFavoriteFilter(moderation_filters.HiddenContentFilterSet): ...@@ -13,6 +13,7 @@ class TrackFavoriteFilter(moderation_filters.HiddenContentFilterSet):
class Meta: class Meta:
model = models.TrackFavorite model = models.TrackFavorite
# XXX: 1.0 remove the user filter, we have scope=me now
fields = ["user", "q", "scope"] fields = ["user", "q", "scope"]
hidden_content_fields_mapping = moderation_filters.USER_FILTER_CONFIG[ hidden_content_fields_mapping = moderation_filters.USER_FILTER_CONFIG[
"TRACK_FAVORITE" "TRACK_FAVORITE"
......
...@@ -154,7 +154,7 @@ services: ...@@ -154,7 +154,7 @@ services:
- "8001:8001" - "8001:8001"
api-docs: api-docs:
image: swaggerapi/swagger-ui:v3.25 image: swaggerapi/swagger-ui:v3.26.0
environment: environment:
- "API_URL=/swagger.yml" - "API_URL=/swagger.yml"
ports: ports:
......
...@@ -26,12 +26,9 @@ info: ...@@ -26,12 +26,9 @@ info:
Authentication Authentication
-------------- --------------
To authenticate, use the `/token/` endpoint with a username and password, and copy/paste To authenticate, use OAuth. You can register your own app using the `/apps` endpoint and proceed to the OAuth flow afterwards.
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 You can use our demo server at `https://demo.funkwhale.audio` for testing purposes.
couple is "demo" and "demo".
Rate limiting Rate limiting
------------- -------------
...@@ -183,6 +180,10 @@ tags: ...@@ -183,6 +180,10 @@ tags:
description: Manipulation and uploading of audio files description: Manipulation and uploading of audio files
externalDocs: externalDocs:
url: https://docs.funkwhale.audio/users/managing.html 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 - name: Content curation
description: Favorites, playlists, radios description: Favorites, playlists, radios
- name: Other - name: Other
...@@ -344,13 +345,8 @@ paths: ...@@ -344,13 +345,8 @@ paths:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- name: "q"
in: "query" - $ref: "#/parameters/Search"
default: null
description: "Search query used to filter artists"
schema:
required: false
type: "string"
- allOf: - allOf:
- $ref: "#/parameters/Ordering" - $ref: "#/parameters/Ordering"
- default: "-creation_date" - default: "-creation_date"
...@@ -365,6 +361,7 @@ paths: ...@@ -365,6 +361,7 @@ paths:
- $ref: "#/parameters/Playable" - $ref: "#/parameters/Playable"
- $ref: "#/parameters/PageNumber" - $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Scope"
responses: responses:
200: 200:
...@@ -436,13 +433,8 @@ paths: ...@@ -436,13 +433,8 @@ paths:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- name: "q"
in: "query" - $ref: "#/parameters/Search"
default: null
description: "Search query used to filter albums"
schema:
required: false
type: "string"
- name: "artist" - name: "artist"
in: "query" in: "query"
default: null default: null
...@@ -465,6 +457,7 @@ paths: ...@@ -465,6 +457,7 @@ paths:
- $ref: "#/parameters/Playable" - $ref: "#/parameters/Playable"
- $ref: "#/parameters/PageNumber" - $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Scope"
responses: responses:
200: 200:
...@@ -538,13 +531,8 @@ paths: ...@@ -538,13 +531,8 @@ paths:
- oauth2: - oauth2:
- "read:libraries" - "read:libraries"
parameters: parameters:
- name: "q"
in: "query" - $ref: "#/parameters/Search"
default: null
description: "Search query used to filter tracks"
schema:
required: false
type: "string"
- name: "artist" - name: "artist"
in: "query" in: "query"
default: null default: null
...@@ -590,6 +578,7 @@ paths: ...@@ -590,6 +578,7 @@ paths:
- $ref: "#/parameters/Playable" - $ref: "#/parameters/Playable"
- $ref: "#/parameters/PageNumber" - $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Scope"
responses: responses:
200: 200:
...@@ -774,6 +763,8 @@ paths: ...@@ -774,6 +763,8 @@ paths:
parameters: parameters:
- $ref: "#/parameters/PageNumber" - $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Search"
- $ref: "#/parameters/Scope"
responses: responses:
200: 200:
content: content:
...@@ -853,11 +844,17 @@ paths: ...@@ -853,11 +844,17 @@ paths:
get: get:
summary: List channels summary: List channels
tags: tags:
- "Uploads and audio content" - "Channels and subscriptions"
parameters: parameters:
- $ref: "#/parameters/PageNumber" - $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Scope" - $ref: "#/parameters/Scope"
- $ref: "#/parameters/Search"
- $ref: "#/parameters/Tags"
- $ref: "#/parameters/Subscribed"
- $ref: "#/parameters/External"
- $ref: "#/parameters/ChannelOrdering"
responses: responses:
200: 200:
content: content:
...@@ -874,7 +871,7 @@ paths: ...@@ -874,7 +871,7 @@ paths:
post: post:
summary: Create a new channel summary: Create a new channel
tags: tags:
- "Uploads and audio content" - "Channels and subscriptions"
responses: responses:
201: 201:
$ref: "#/responses/201" $ref: "#/responses/201"
...@@ -887,6 +884,53 @@ paths: ...@@ -887,6 +884,53 @@ paths:
schema: schema:
$ref: "#/definitions/ChannelCreate" $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}/: /api/v1/channels/{uuid}/:
parameters: parameters:
- name: uuid - name: uuid
...@@ -898,7 +942,7 @@ paths: ...@@ -898,7 +942,7 @@ paths:
get: get:
summary: Retrieve a channel summary: Retrieve a channel
tags: tags:
- "Uploads and audio content" - "Channels and subscriptions"
responses: responses:
200: 200:
content: content:
...@@ -908,7 +952,7 @@ paths: ...@@ -908,7 +952,7 @@ paths:
post: post:
summary: Update a channel summary: Update a channel
tags: tags:
- "Uploads and audio content" - "Channels and subscriptions"
requestBody: requestBody:
required: true required: true
content: content:
...@@ -927,27 +971,97 @@ paths: ...@@ -927,27 +971,97 @@ paths:
This will delete the channel, all associated uploads, follows, and broadcast This will delete the channel, all associated uploads, follows, and broadcast
the event on the federation. the event on the federation.
tags: tags:
- "Uploads and audio content" - "Channels and subscriptions"
responses: responses:
204: 204:
$ref: "#/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/: /api/v1/uploads/:
get: get:
summary: List owned uploads summary: List owned uploads
tags: tags:
- "Uploads and audio content" - "Uploads and audio content"
parameters: parameters:
- name: "q"
in: "query" - $ref: "#/parameters/Search"
default: null
description: "Search query used to filter uploads"
schema:
required: false
type: "string"
example: "Dire straits"
- $ref: "#/parameters/PageNumber" - $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Scope"
responses: responses:
200: 200:
content: content:
...@@ -1004,6 +1118,61 @@ paths: ...@@ -1004,6 +1118,61 @@ paths:
$ref: "#/definitions/ImportMetadata" $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}/: /api/v1/uploads/{uuid}/:
parameters: parameters:
- name: uuid - name: uuid
...@@ -1076,21 +1245,11 @@ paths: ...@@ -1076,21 +1245,11 @@ paths:
tags: tags:
- "Content curation" - "Content curation"
parameters: parameters:
- name: "q" - $ref: "#/parameters/Search"
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/PageNumber"
- $ref: "#/parameters/PageSize" - $ref: "#/parameters/PageSize"
- $ref: "#/parameters/Scope"
responses: responses:
200: 200:
content: content:
...@@ -1205,6 +1364,28 @@ paths: ...@@ -1205,6 +1364,28 @@ paths:
$ref: "#/responses/204" $ref: "#/responses/204"
parameters: 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: ObjectId:
name: id name: id
in: path in: path
...@@ -1258,13 +1439,51 @@ parameters: ...@@ -1258,13 +1439,51 @@ parameters:
name: "scope" name: "scope"
in: "query" in: "query"
default: "all" 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: schema:
required: false required: false
type: "string" type: "string"
enum: enum:
- "me" - "me"
- "all" - "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: responses:
200: 200:
description: Success description: Success
...@@ -1276,6 +1495,26 @@ responses: ...@@ -1276,6 +1495,26 @@ responses:
description: Bad request description: Bad request
properties: 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: