Django Views

The REST API is implemented with Django REST Framework class-based views in cdb_rest/views.py. For endpoint URLs, parameters, and example requests, see API Documentation; this page is the code-level reference.

View Categories

Global Tag views

List, retrieve (by ID or name), create, clone, delete, and change the status of Global Tags. Deletion and status changes enforce the locked/frozen immutability rules.

Payload Type views

List, create, and delete payload types. Deletion is refused while any PayloadList still references the type.

Payload List views

List and create payload lists (names are auto-generated from the payload type and a sequence ID), attach lists to Global Tags, and delete empty lists.

Payload IOV views

Create payload IOVs (single or bulk), attach them to payload lists with overlap resolution, delete them, and query them. IOV validation and overlap handling delegate to the mode strategies in cdb_rest/iov_comparisons.py (CDB_IOV_MODE).

Query views

PayloadIOVsSQLListAPIView backs the main /payloadiovs/ endpoint. It executes a raw SQL query from cdb_rest/queries.py (selected by the CDB_PAYLOAD_IOVS_QUERY setting) and distributes reads across the configured read_db_* replicas.

Settings view

CDBSettingAPIView exposes CDB_* environment variables read-only.

Authentication and Permissions

All views mix in WriteAuthMixin: when CDB_AUTH_CLASS is set, write methods (POST/PUT/PATCH/DELETE) authenticate with the configured class while reads stay anonymous. Write views additionally call the permission plugin loaded from CDB_PERMISSION_PLUGIN_CLASS (see cdb_rest/permissions_plugins/) before modifying data.

View Reference

The following documentation is generated from the view classes and their docstrings.

class cdb_rest.views.WriteAuthMixin

Bases: object

Require JWT authentication for write methods (POST/PUT/PATCH/DELETE), allow anonymous reads.

get_authenticators()

cdb_rest.views.paginate_browse(request, queryset, serializer_class, search_fields, sort_map, default_sort)

Server-side search/sort/pagination for browse endpoints (opt-in via ?page=).

Returns {count, page, page_size, total_pages, results}. Sort fields are whitelisted through sort_map to prevent ordering by arbitrary columns.

class cdb_rest.views.GlobalTagDetailAPIView(**kwargs)

Bases: WriteAuthMixin, RetrieveAPIView

serializer_class

alias of GlobalTagReadSerializer

queryset = QuerySet

class cdb_rest.views.GlobalTagByNameDetailAPIView(**kwargs)

Bases: WriteAuthMixin, RetrieveAPIView

Retrieve a GlobalTag by name with all nested PayloadLists and IOVs.

Pass ?light=1 to get metadata only (no nested payload lists), with payload list / IOV counts computed in the database.

serializer_class

alias of GlobalTagReadSerializer

queryset = QuerySet

lookup_url_kwarg = 'globalTagName'

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.

retrieve(request, *args, **kwargs)

class cdb_rest.views.TimeoutListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

Test endpoint that simulates a long-running request (30 min timeout).

list(request)

class cdb_rest.views.GlobalTagListCreationAPIView(**kwargs)

Bases: WriteAuthMixin, ListCreateAPIView

List all GlobalTags (GET) or create a new one (POST). Requires admin permission to create.

serializer_class

alias of GlobalTagCreateSerializer

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)

list(request)

create(request, *args, **kwargs)

class cdb_rest.views.GlobalTagDeleteAPIView(**kwargs)

Bases: WriteAuthMixin, DestroyAPIView

Delete a GlobalTag by name. Locked and frozen GTs are immutable.

serializer_class

alias of GlobalTagReadSerializer

lookup_url_kwarg = 'globalTagName'

lookup_field = 'name'

get_gtag()

destroy(request, *args, **kwargs)

class cdb_rest.views.PayloadIOVDeleteAPIView(**kwargs)

Bases: WriteAuthMixin, DestroyAPIView

Delete a PayloadIOV. Frozen GTs are immutable.

serializer_class

alias of PayloadIOVSerializer

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.

destroy(request, *args, **kwargs)

class cdb_rest.views.PayloadTypeDeleteAPIView(**kwargs)

Bases: WriteAuthMixin, DestroyAPIView

Delete a PayloadType. Fails if any PayloadLists reference it.

serializer_class

alias of PayloadTypeSerializer

get_ptype()

get_plists(ptype)

destroy(request, *args, **kwargs)

class cdb_rest.views.PayloadListDeleteAPIView(**kwargs)

Bases: WriteAuthMixin, DestroyAPIView

Delete a PayloadList. Fails if it contains any PayloadIOVs.

serializer_class

alias of PayloadListSerializer

get_plist()

get_piovs(plist)

destroy(request, *args, **kwargs)

class cdb_rest.views.GlobalTagsListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

List all GlobalTags with attached PayloadLists summary.

Pass ?page= to get a paginated response with server-side search (?search=), status filter (?status=) and sorting (?sort=&order=).

serializer_class

alias of GlobalTagListSerializer

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)

list(request)

class cdb_rest.views.GlobalTagsDetailedListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

List all GlobalTags with status name and per-tag payload counts.

serializer_class

alias of GlobalTagDetailedSerializer

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 cdb_rest.views.GlobalTagsPayloadListsListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

List PayloadLists for a given GlobalTag as a {payload_type: name} map.

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)

list(request, *args, **kwargs)

class cdb_rest.views.GlobalTagStatusCreationAPIView(**kwargs)

Bases: WriteAuthMixin, ListCreateAPIView

List or create GlobalTag statuses (unlocked, locked, frozen).

serializer_class

alias of GlobalTagStatusSerializer

lookup_field = 'name'

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)

list(request)

create(request, *args, **kwargs)

class cdb_rest.views.PayloadListListCreationAPIView(**kwargs)

Bases: WriteAuthMixin, ListCreateAPIView

List all PayloadLists (GET) or create a new one (POST). Auto-generates name from PayloadType + sequence ID.

Pass ?page= to get a paginated response without nested IOVs, with server-side search (?search=), filters (?global_tag=, ?payload_type=) and sorting (?sort=&order=).

serializer_class

alias of PayloadListCreateSerializer

static get_next_id()

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)

list(request)

create(request, *args, **kwargs)

class cdb_rest.views.PayloadListDetailAPIView(**kwargs)

Bases: WriteAuthMixin, RetrieveAPIView

serializer_class

alias of PayloadListCreateSerializer

queryset = QuerySet

class cdb_rest.views.PayloadListByNameAPIView(**kwargs)

Bases: WriteAuthMixin, RetrieveAPIView

Retrieve a PayloadList by name (metadata + IOV count, no nested IOVs).

serializer_class

alias of PayloadListBrowseSerializer

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 cdb_rest.views.PayloadTypeListCreationAPIView(**kwargs)

Bases: WriteAuthMixin, ListCreateAPIView

List all PayloadTypes (GET) or create a new one (POST).

Pass ?page= to get a paginated response with server-side search (?search=) and sorting (?sort=&order=).

serializer_class

alias of PayloadTypeSerializer

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)

list(request)

create(request, *args, **kwargs)

class cdb_rest.views.PayloadIOVListCreationAPIView(**kwargs)

Bases: WriteAuthMixin, ListCreateAPIView

List all PayloadIOVs (GET) or create a new one (POST). Validates IOV ranges based on CDB_IOV_MODE.

Pass ?page= to get a paginated response of flat rows including payload list / global tag / payload type names, with server-side search (?search=), filters (?payload_list=, ?global_tag=, ?payload_type=) and sorting (?sort=&order=).

serializer_class

alias of PayloadIOVSerializer

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)

list(request)

create(request, *args, **kwargs)

class cdb_rest.views.PayloadIOVDetailAPIView(**kwargs)

Bases: WriteAuthMixin, RetrieveAPIView

serializer_class

alias of PayloadIOVSerializer

queryset = QuerySet

class cdb_rest.views.PayloadIOVBulkCreationAPIView(**kwargs)

Bases: WriteAuthMixin, CreateAPIView

Bulk-create PayloadIOVs from a JSON array. Skips individual validation for performance.

serializer_class

alias of PayloadIOVSerializer

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)

create(request, *args, **kwargs)

class cdb_rest.views.GlobalTagCloneAPIView(**kwargs)

Bases: WriteAuthMixin, CreateAPIView

Deep-copy a GlobalTag: duplicates the GT, all its PayloadLists, and their PayloadIOVs.

serializer_class

alias of GlobalTagReadSerializer

get_global_tag()

get_clone_name()

static get_payload_lists(global_tag)

static get_payload_iovs(payload_list)

static get_next_id()

create(request, globalTagName, cloneName)

class cdb_rest.views.PayloadIOVsORMMaxListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

Get latest PayloadIOVs per PayloadList for a given GT and IOV point, using ORM MAX aggregation.

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)

list(request)

class cdb_rest.views.PayloadIOVsORMOrderByListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

Get latest PayloadIOVs per PayloadList using ORM ORDER BY + DISTINCT.

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)

list(request)

class cdb_rest.views.PayloadIOVsSQLListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

Get PayloadIOVs using raw SQL for performance. Distributes reads across read replicas.

list(request)

class cdb_rest.views.PayloadIOVsRangesListAPIView(**kwargs)

Bases: WriteAuthMixin, ListAPIView

Get PayloadIOVs within a given IOV range, grouped by PayloadList.

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)

list(request)

class cdb_rest.views.PayloadListAttachAPIView(**kwargs)

Bases: WriteAuthMixin, UpdateAPIView

Attach a PayloadList to a GlobalTag. Detaches any existing list of the same PayloadType first.

serializer_class

alias of PayloadListCreateSerializer

put(request, *args, **kwargs)

class cdb_rest.views.PayloadIOVAttachAPIView(**kwargs)

Bases: WriteAuthMixin, UpdateAPIView

Attach a PayloadIOV to a PayloadList. Handles overlap resolution: - Locked GT: rejects conflicting IOVs (append-only), with special case for open-ended Online GT IOVs. - Unlocked GT: splits/trims existing IOVs to accommodate the new one.

serializer_class

alias of PayloadIOVSerializer

put(request, *args, **kwargs)

class cdb_rest.views.GlobalTagChangeStatusAPIView(**kwargs)

Bases: WriteAuthMixin, UpdateAPIView

Change a GlobalTag’s status (e.g. unlocked -> locked -> frozen).

serializer_class

alias of GlobalTagCreateSerializer

get_global_tag()

get_gt_status()

put(request, *args, **kwargs)

class cdb_rest.views.CDBSettingAPIView(**kwargs)

Bases: WriteAuthMixin, APIView

Expose CDB_* environment variables as read-only settings.

get(request, name)

class cdb_rest.views.AuthDecisionAPIView(**kwargs)

Bases: APIView

Authorization decision endpoint for nginx auth_request subrequests.

nginx passes the original request’s method and URI in the X-Original-Method and X-Original-URI headers. Reads are always allowed, file uploads (PUT) require authentication and the permission plugin’s approval, and any other method is denied. Returns 200 to allow, 401/403 to deny; no response body is needed.

get_authenticators()

Instantiates and returns the list of authenticators that this view can use.

get(request)

cdb_rest.views.cdb_web_view(request)

Render the Conditions Database web interface.

See Also

• API Documentation - Complete API endpoint documentation

• Database Models - Database models used by these views

• Architecture - Overall system architecture and design