Pirate Wiki

Toggle Theme

Metadata ​

Metadata provides information about your API endpoints. It describes what HTTP methods are supported, what data formats are accepted and detailed specifications about the fields your API expects.

Clients retrieve this information by sending an HTTP OPTIONS request to the endpoint. This is incredibly powerful for building dynamic frontend forms, self-documenting APIs, or auto-generating client SDKs.

The OPTIONS Response ​

By default, an OPTIONS request returns a JSON dictionary containing metadata. The core structure includes:

  • name: The human-readable name of the view.
  • description: The view's description (pulled from its Python docstring).
  • renders: A list of media types the API can respond with (e.g., ["application/json"]).
  • parses: A list of media types the API can accept in requests (e.g., ["application/json", "multipart/form-data"]).
  • actions: If the view accepts POST or PUT requests, this contains detailed field-level information (type, required status, read-only status, choices, etc.) about the expected input data.

Setting Metadata Classes ​

DRF uses SimpleMetadata by default. You can explicitly configure the metadata class globally in your settings.py:

python
REST_FRAMEWORK = {
    'DEFAULT_METADATA_CLASS': 'rest_framework.metadata.SimpleMetadata'
}

Or you can configure it on a per-view basis:

Class-Based Views ​

python
from rest_framework.metadata import SimpleMetadata
from rest_framework.views import APIView

class ExampleView(APIView):
    # Set to a specific class, or set to None to disable OPTIONS requests entirely
    metadata_class = SimpleMetadata

NOTE

Function-based views (@api_view) always use the globally configured metadata class. There is no decorator to override it on a per-view basis.

Custom Metadata ​

If you want to alter the structure of the OPTIONS response, perhaps to include custom permissions data, pagination limits, or a custom field structure, you can build a custom metadata class.

Subclass BaseMetadata and implement the determine_metadata(self, request, view) method, which must return a dictionary.

python
from rest_framework.metadata import BaseMetadata

class CustomMetadata(BaseMetadata):
    """
    A custom metadata class that strips down the OPTIONS response 
    to just the basics and adds a custom versioning string.
    """
    def determine_metadata(self, request, view):
        return {
            'name': view.get_view_name(),
            'description': view.get_view_description(),
            'version': 'v2.0',
            'supported_methods': view.allowed_methods
        }

You can then apply this CustomMetadata class globally or to specific views.

TIP

While OPTIONS metadata is built-in, many developers use third-party packages like drf-spectacular or drf-yasg to generate comprehensive OpenAPI (Swagger) schemas instead.