The conflict responses should be send with an HTTP 409 status code as
they’re defined in our documentation. This was not the case as the
dashboard couldn’t handle these error codes, but is now fixed in
dashboard@4a07ad9e.

Until now the steering API client was expected to submit two requests.

1. The initial schedule request, with a `schedule` object
2. A second schedule request, with an additional `solutions` object

This `solutions` object was empty, if no conflicts arose from the
submitted schedule in the first place. But instead of just creating the
requested schedule if no conflicts were detected we still required that
second round-trip, introducing possible race conditions in the client,
if another successful scheduling request was made between requests.

From now on the steering API will create schedules if no conflicts have
been detected and will only require the client to submit solutions if
there really are conflicts to solve.

The following attribute names were marked as deprecated in the schedule
request and have been replaced by their new names:

  dstart → first_date
  until → last_date
  tstart → start_time
  tend → end_time
  byweekday → by_weekday

Apart from that this commit fixes a few documentation errors.

When making the serialized fields explicit in
0ee3a655 we forgot to add the id field
that is used in various places.

If a collection is filtered by an invalid id (meaning the model the
query argument points to with that specific id does not exist), we no
longer return an error. Instead the filter is applied without a lookup.

Fixes #104

This adds extensive API documentation based on the official API
documentation [1] and conflict resolution [2] documents.

Where possible field documentation was added to models or serializers,
so that other code like auto-generated forms can also profit from these
changes (hence the migration part of this commit).

The changes introduce two new API endpoints.

`/api/v1/schema/` exposes the API schema as an OpenAPI 3.0.3 document.
The standard format is yaml but can be switched to JSON by appending the
`?format=json` query parameter.

`/api/v1/schema/swagger-ui/` renders a visual representation of the
OpenAPI 3 specification with support for testing the individual API
endpoints including authentication.

[1]
https://gitlab.servus.at/aura/meta/-/blob/ec3c753d34ccb0269969808ac7dc28fff2ff1648/docs/development/api-definition.md
[2]
https://gitlab.servus.at/aura/meta/-/blob/ec3c753d34ccb0269969808ac7dc28fff2ff1648/docs/development/conflict-resolution.md

In addition to the

	?foo=1,2,3

filter syntax we now also support

	?foo=1&foo=2&foo=3
	?foo[]=1&foo[]=2&foo[]=3

Schedule dry-runs returned a 201 response before, because the only check
for a 201 return code was, that the payload must not contain the
"projected" keyword.

As dry-runs don’t create any data 201 is not an appropriate status code.

The filter defaults caused the queryset to always yield results filtered
for the coming 60 days. We should only apply filter defaults when
listing timeslots, not when querying individual items.

The retrieve and update actions can be removed because the get_queryset
method already ensures that the user has only access to their own user
object (or all user objects in case of superusers).

Sending 401 responses for unauthorized requests may also be considered
leaky, because it exposes that these objects exist instead of returning
a 404 that simply states that no object with that primary key can be
found.

Simply omitting properties in the API in certain edge cases makes API
client implementations brittle and documentation a lot harder.

This gives the calling code better control over the handling of such
errors and makes it easy to differentiate between errors and valid
return types.

Most of the queryset filtering for subroutes formerly implemented
through custom get_queryset methods can happen semi-automated through a
mixin, making the behaviour re-usable and allowing us strip a lot of
additional logic for retrieving objects.

The use of the viewset get_object method also allows us to implement
object access with permission classes in the future, and should make a
whole lot of other code obselete.

This change is primarily motivated by the fact that documentation of the
API will become a lot easier if the subroutes don’t impose arbitrary
restrictions on the specific subpath under which an operation is
allowed. For instance updating a schedule should be possible through
either /schedules/<pk>/ or
/shows/<show_pk>/schedules/<schedule_pk>/ as long as all the necessary
data is present in the request body.

The show retrieve method allowed shows to be identified through the slug
or the id. This is handy, but was restricted to the retrieve and did not
apply to the update nor delete methods. The proper way to implement this
kind of behaviour is through overriding get_object so that route
identifiers are handled consistently.

cba_id was always part of the serialized note representation through the
use of `fields = "__all__"``and shouldn’t be write-only.

This adds extensive API documentation based on the official API
documentation [1] and conflict resolution [2] documents.

Where possible field documentation was added to models or serializers,
so that other code like auto-generated forms can also profit from these
changes (hence the migration part of this commit).

The changes introduce two new API endpoints.

`/api/v1/schema/` exposes the API schema as an OpenAPI 3.0.3 document.
The standard format is yaml but can be switched to JSON by appending the
`?format=json` query parameter.

`/api/v1/schema/swagger-ui/` renders a visual representation of the
OpenAPI 3 specification with support for testing the individual API
endpoints including authentication.

[1]
https://gitlab.servus.at/aura/meta/-/blob/ec3c753d34ccb0269969808ac7dc28fff2ff1648/docs/development/api-definition.md
[2]
https://gitlab.servus.at/aura/meta/-/blob/ec3c753d34ccb0269969808ac7dc28fff2ff1648/docs/development/conflict-resolution.md

In addition to the

	?foo=1,2,3

filter syntax we now also support

	?foo=1&foo=2&foo=3
	?foo[]=1&foo[]=2&foo[]=3

Schedule dry-runs returned a 201 response before, because the only check
for a 201 return code was, that the payload must not contain the
"projected" keyword.

As dry-runs don’t create any data 201 is not an appropriate status code.

The filter defaults caused the queryset to always yield results filtered
for the coming 60 days. We should only apply filter defaults when
listing timeslots, not when querying individual items.

The retrieve and update actions can be removed because the get_queryset
method already ensures that the user has only access to their own user
object (or all user objects in case of superusers).

Sending 401 responses for unauthorized requests may also be considered
leaky, because it exposes that these objects exist instead of returning
a 404 that simply states that no object with that primary key can be
found.

Simply omitting properties in the API in certain edge cases makes API
client implementations brittle and documentation a lot harder.

This gives the calling code better control over the handling of such
errors and makes it easy to differentiate between errors and valid
return types.

Most of the queryset filtering for subroutes formerly implemented
through custom get_queryset methods can happen semi-automated through a
mixin, making the behaviour re-usable and allowing us strip a lot of
additional logic for retrieving objects.

The use of the viewset get_object method also allows us to implement
object access with permission classes in the future, and should make a
whole lot of other code obselete.

This change is primarily motivated by the fact that documentation of the
API will become a lot easier if the subroutes don’t impose arbitrary
restrictions on the specific subpath under which an operation is
allowed. For instance updating a schedule should be possible through
either /schedules/<pk>/ or
/shows/<show_pk>/schedules/<schedule_pk>/ as long as all the necessary
data is present in the request body.

The show retrieve method allowed shows to be identified through the slug
or the id. This is handy, but was restricted to the retrieve and did not
apply to the update nor delete methods. The proper way to implement this
kind of behaviour is through overriding get_object so that route
identifiers are handled consistently.

cba_id was always part of the serialized note representation through the
use of `fields = "__all__"``and shouldn’t be write-only.

This change re-implements all existing collection filters for the
APINoteViewSet with a FilterSet. No breaking changes are expected.

* TODOs are no longer part of the method description
* normalized queryset handling
* consistent formatting of method descriptions.

If notes are created through subroutes some of the data necessary to
create a note is already available through the route data and doesn’t
need to be passed as part of the request body anymore.

Notes will only be created if called through a timeslot subroute. The
typo prohibited the note creation, because timeslot_pk was always None
and caused the view to error early.

This adds a string representation for all program models except the
schedule so that it is easier to identify objects in DRF’s filter,
create, and update forms.

There were some problems during audio_url generation for notes:

1. the cba_id was never part of the Note serializer so getting
   values from the validated data needed to fail.
2. the get_audio_url utililty function returned None if
   no cba_id was provided if a the CBA_API_KEY was missing,
   but None but the respective model field is not nullable on the note.
3. Request or JSON decoder errors would bubble unhandled, even though
   audio_url generation seems to be optional and should not necessarily
   interfere with note creation.

APICategoryViewSet, APITypeViewSet, APITopicViewSet,
APIMusicFocusViewSet, APIFundingCategoryViewSet, APILanguageViewSet, and
APIHostViewSet all used the same base class implementing get_queryset
for filtering by their active state. This is now handled by a generic
FilterSet.