Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in / Register
Toggle navigation
Menu
Open sidebar
Philipp Wolfer
funkwhale
Commits
4db0b9b4
Commit
4db0b9b4
authored
Jun 15, 2020
by
Agate
💬
Browse files
Channels api docs
parent
5de006b9
Changes
3
Hide whitespace changes
Inline
Side-by-side
api/funkwhale_api/favorites/filters.py
View file @
4db0b9b4
...
...
@@ -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"
...
...
dev.yml
View file @
4db0b9b4
...
...
@@ -154,7 +154,7 @@ services:
-
"
8001:8001"
api-docs
:
image
:
swaggerapi/swagger-ui:v3.2
5
image
:
swaggerapi/swagger-ui:v3.2
6.0
environment
:
-
"
API_URL=/swagger.yml"
ports
:
...
...
docs/swagger.yml
View file @
4db0b9b4
...
...
@@ -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"