Skip to content

4. The schema and languages

The schema says what arrives

drf-spectacular reads serializers, so on its own it documents what is inside the envelope - and a client generated from it writes response.id where the truth is response.data.id. ParcelAutoSchema documents the envelope itself. Open http://127.0.0.1:8000/api/docs/:

  • every success of a view with the mixin is the envelope, with data the serializer - and a delete the 200 it answers;
  • each page is its own component, named for its kind - ProductPage, OrderCursorPage;
  • page_size appears on products, with its ceiling as the maximum, and not on orders;
  • every operation's default answer is ErrorEnvelope, and an operation that takes a body has ValidationErrorEnvelope as its 400.

A view left out of the envelope is documented as it answers:

example/shop/api.py
class HealthView(EnvelopeMixin, APIView):
    """Asked by a load balancer that expects {"ok": true} - so it stays out of the envelope."""

    parcel_wrap = False

    @extend_schema(responses=inline_serializer('Health', fields={'ok': serializers.BooleanField()}))
    def get(self, request: Request) -> Response:
        return Response({'ok': True})

Answering in Persian

With LocaleMiddleware, the language is the request's:

curl -H 'Accept-Language: fa' http://127.0.0.1:8000/api/products/1/

The same envelope, its message - "Done." - said in Persian. The keys, the codes and the data do not change: only what a person reads does.

Every sentence the library says comes in Persian. DRF's own - "This field is required." - comes in DRF's languages. Your own messages, marked with gettext_lazy, are translated in your project's catalogue.

Where to go from here

  • How-to guides - adopting it in an existing project, reading the envelope from a frontend, testing.
  • The contract - every shape and code.