REST API

The api module implements a REST-ful API for the media service based on the Django REST Framework.

Installation

Add api to the INSTALLED_APPS setting and then update your urlpatterns as follows:

urlpatterns = [
    # ...
    path('api/', include('api.urls', namespace='api')),
    # ...
]

Views

Views implementing the API endpoints.

api.views.POSTER_IMAGE_VALID_WIDTHS = [320, 480, 640, 720, 1280, 1920]

Allowed poster image widths

api.views.POSTER_IMAGE_DEFAULT_WIDTH = 720

Default poster image width

api.views.POSTER_IMAGE_VALID_EXTENSIONS = ['jpg']

Allowed poster image extensions

class api.views.ListPagination

class api.views.FullTextSearchFilter

Custom filter based on rest_framework.filters.SearchFilter specialised to search object with a full-text search SearchVectorField. Unlike the standard search filter, this class accepts only one search field to be set in search_fields.

The filter always annotates the objects with a search rank. The name is “search_rank” by default but can be overridden by setting search_rank_annotation on the view. If the search is empty then this rank will always be zero.

filter_queryset(request, queryset, view)

Return a filtered queryset.

class api.views.ViewMixinBase

A generic mixin class for API views which provides helper methods to filter querysets of MediaItem, Channel and Playlist objects for the request user and to be annotated with all of the fields required by the non-detail serialisers.

Additionally, there are helper methods to annotate a query set with fields required by the detail serialisers.

It also defines an appropriate permission class to forbid non-editors from performing “unsafe” operations on the objects.

filter_media_item_qs(qs)

Filters a MediaItem queryset so that only the appropriate objects are returned for the user, annotates the objects with any fields required by the serialisers and selects any related objects used by the serialisers.

filter_channel_qs(qs)

Filters a Channel queryset so that only the appropriate objects are returned for the user, annotates the objects with any fields required by the serialisers and selects any related objects used by the serialisers.

filter_playlist_qs(qs)

Filters a Playlist queryset so that only the appropriate objects are returned for the user, annotates the objects with any fields required by the serialisers and selects any related objects used by the serialisers.

filter_billing_account_qs(qs)

Filters a BillingAccount queryset so that only the appropriate objects are returned for the user, annotates the objects with any fields required by the serialisers and selects any related objects used by the serialisers.

add_media_item_detail(qs)

Add any extra annotations to a MediaItem query set which are required to render the detail view via MediaItemDetailSerializer.

add_channel_detail(qs, name='item_count')

Add any extra annotations to a Channel query set which are required to render the detail view via ChannelDetailSerializer.

add_playlist_detail(qs)

Add any extra annotations to a Playlist query set which are required to render the detail view via PlaylistDetailSerializer.

get_profile()

Return an object representing what is known about a user from the request. The object can eb serialised with api.serializers.ProfileSerializer.

class api.views.ProfileView(**kwargs)

Endpoint to retrieve the profile of the current user.

serializer_class

alias of api.serializers.ProfileSerializer

get_object()

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class api.views.MediaItemListMixin

A mixin class for DRF generic views which has all of the specialisations necessary for listing (and possibly creating/deleting) media items. Use this mixin with ListAPIView or ListCreateAPIView to form a concrete view class.

class api.views.MediaItemMixin

A mixin class for DRF generic views which has all of the specialisations necessary for retrieving (and possibly updating) individual media items. Use this mixin with RetrieveAPIView or RetrieveUpdateAPIView to form a concrete view class.

class api.views.MediaItemListView(**kwargs)

List and search Media items. If no other ordering is specified, results are returned in order of decreasing search relevance (if there is any search) and then by decreasing publication date.

pagination_class

alias of ListPagination

serializer_class

alias of api.serializers.MediaItemSerializer

get_queryset()

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

class api.views.MediaItemView(**kwargs)

Endpoint to retrieve a single media item.

serializer_class

alias of api.serializers.MediaItemDetailSerializer

class api.views.MediaItemUploadView(**kwargs)

Endpoint for retrieving an upload URL for a media item. Requires that the user have the edit permission for the media item. Should the upload URL be expired or otherwise unsuitable, a HTTP POST/PUT to this endpoint refreshes the URL.

serializer_class

alias of api.serializers.MediaUploadSerializer

get_queryset()

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

class api.views.MediaItemSourceView(**kwargs)

Endpoint to retrieve a media item source stream

class api.views.MediaItemAnalyticsView(**kwargs)

Endpoint to retrieve the analytics for a single media item.

serializer_class

alias of api.serializers.MediaItemAnalyticsListSerializer

class api.views.MediaItemPosterView(**kwargs)

Retrieve a poster image for a media item.

class api.views.ChannelListMixin

A mixin class for DRF generic views which has all of the specialisations necessary for listing (and possibly creating/deleting) channels. Use this mixin with ListAPIView or ListCreateAPIView to form a concrete view class.

class api.views.ChannelMixin

A mixin class for DRF generic views which has all of the specialisations necessary for retrieving (and possibly updating) individual channels. Use this mixin with RetrieveAPIView or RetrieveUpdateAPIView to form a concrete view class.

class api.views.ChannelListView(**kwargs)

Endpoint to retrieve a list of channels. List and search Channels. If no other ordering is specified, results are returned in order of decreasing search relevance (if there is any search) and then by decreasing update date.

pagination_class

alias of ListPagination

serializer_class

alias of api.serializers.ChannelSerializer

get_queryset()

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

class api.views.ChannelView(**kwargs)

Endpoint to retrieve an individual channel.

serializer_class

alias of api.serializers.ChannelDetailSerializer

class api.views.PlaylistListMixin

A mixin class for DRF generic views which has all of the specialisations necessary for listing (and possibly creating/deleting) playlists. Use this mixin with ListAPIView or ListCreateAPIView to form a concrete view class.

class api.views.PlaylistMixin

A mixin class for DRF generic views which has all of the specialisations necessary for retrieving (and possibly updating) individual playlists. Use this mixin with RetrieveAPIView or RetrieveUpdateAPIView to form a concrete view class.

class api.views.PlaylistListView(**kwargs)

Endpoint to retrieve a list of playlists. List and search Playlists. If no other ordering is specified, results are returned in order of decreasing search relevance (if there is any search) and then by decreasing update date.

pagination_class

alias of ListPagination

serializer_class

alias of api.serializers.PlaylistSerializer

get_queryset()

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

class api.views.PlaylistView(**kwargs)

Endpoint to retrieve an individual playlists.

serializer_class

alias of api.serializers.PlaylistDetailSerializer

get_object()

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class api.views.BillingAccountListMixin

A mixin class for DRF generic views which has all of the specialisations necessary for listing billing accounts.

class api.views.BillingAccountMixin

A mixin class for DRF generic views which has all of the specialisations necessary for retrieving (and possibly updating) individual nilling accounts.

class api.views.BillingAccountListView(**kwargs)

Billing accounts.

pagination_class

alias of ListPagination

serializer_class

alias of api.serializers.BillingAccountSerializer

get_queryset()

Get the list of items for this view. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

This method should always be used rather than accessing self.queryset directly, as self.queryset gets evaluated only once, and those results are cached for all subsequent requests.

You may want to override this if you need to provide different querysets depending on the incoming request.

(Eg. return a list of items that is specific to the user)

class api.views.BillingAccountView(**kwargs)

Billing account.

serializer_class

alias of api.serializers.BillingAccountDetailSerializer

Serializers

class api.serializers.RelatedBillingAccountIdField(**kwargs)

Related field serializer which asserts that the billing account field can only be set to a billing account which allows the current user permission to create channels. If there is no user, the empty queryset is returned.

class api.serializers.ChannelSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual channel.

create(validated_data)

Override behaviour when creating a new object using this serializer. If the current request is being passed in the context, give the request user edit and view permissions on the item.

update(instance, validated_data)

Override behaviour when updating to stop the user changing the billing account of an existing object.

class api.serializers.RelatedChannelIdField(**kwargs)

Related field serializer for media items or playlists which asserts that the channel field can only be set to a channel which the current user has edit permissions on. If there is no user, the empty queryset is returned.

class api.serializers.ChannelOwnedResourceModelSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

Shared ModelSerializer between Media Items and Playlists as both are owned by a channel

update(instance, validated_data)

Override behaviour when updating a media item or a playlist to stop the user changing the channel of an existing object.

class api.serializers.PlaylistSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual playlist.

class api.serializers.MediaItemSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual media item.

create(validated_data)

Override behaviour when creating a new object using this serializer. If the current request is being passed in the context, give the request user edit and view permissions on the item.

class api.serializers.BillingAccountSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual billing account.

class api.serializers.SourceSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

A download source for a particular media type.

class api.serializers.MediaUploadSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

A serializer which returns an upload endpoint for a media item. Intended to be used as custom serializer in an UpdateView for MediaItem models.

class api.serializers.MediaItemDetailSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual media item including related resources.

class api.serializers.MediaItemAnalyticsSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

The number of viewing for a particular media item on a particular day.

class api.serializers.MediaItemAnalyticsListSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

A list of media analytics data points.

class api.serializers.ChannelDetailSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual channel including related resources.

class api.serializers.PlaylistDetailSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual playlist including any information which should only appear in the detail view.

class api.serializers.ProfileSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

The profile of the current user.

class api.serializers.BillingAccountDetailSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)

An individual billing account including related resources.