What is the benefit of using a HyperlinkedModelSerializer in DRF?

Question

In reference to this link, I've seen plenty of examples of using a HyperlinkedModelSerializer in Django Rest Framework. It says:

The HyperlinkedModelSerializer class is similar to the ModelSerializer class except that it uses hyperlinks to represent relationships, rather than primary keys.

My question is, what is the use case/benefit of using them vs a regular Model Serializer?

Answer 1

We need to implement relationship between entities in Web API design. There are several ways to do that (as mentions on DRF documentation):

• Using primary keys.
• Using hyperlinking between entities.
• Using a unique identifying slug field on the related entity.
• Using the default string representation of the related entity.
• Nesting the related entity inside the parent representation.
• Some other custom representation

The HyperlinkedModelSerializer has the following differences from ModelSerializer:

• It does not include the id field by default.
• It includes a url field, using HyperlinkedIdentityField.
• Relationships use HyperlinkedRelatedField, instead of PrimaryKeyRelatedField.

A simple example:

class UserSerializer(serializers.HyperlinkedModelSerializer):     class Meta:         model = User         fields = ('url', 'username', 'email', 'groups')   class GroupSerializer(serializers.HyperlinkedModelSerializer):     class Meta:         model = Group         fields = ('url', 'name') 

bash> http -a admin:yourpassword http://127.0.0.1:8000/users/

 "results": [         {             "email": "[email protected]",             "groups": [                 "http://127.0.0.1:8000/groups/1/",                 "http://127.0.0.1:8000/groups/2/"             ],             "url": "http://127.0.0.1:8000/users/1/",             "username": "admin"         }     ] 

But if you change

class UserSerializer(serializers.ModelSerializer):         class Meta:             model = User             fields = ('url', 'username', 'email', 'groups') 

The result will be:

   "results": [         {             "email": "[email protected]",             "groups": [                 1,                 2             ],             "url": "http://127.0.0.1:8000/users/1/",             "username": "admin"         }     ] 

Answer 2

The only difference is, as in citation you included, that primary and foreign keys are represented by URLs that point to those resources, instead of just actual key values.

The benefit is that you will not have to construct resource URLs in your frontend when you want to retrieve related objects.

Another thing entirely is nested representations which allows you to inline related objects in your serializer output. This can be combined with both ModelSerializer and HyperlinkedModelSerializer when you think that it is more convenient for the API consumer to have related items right away instead of making additional requests to retrieve them.

Nested representations can be implemented via the Meta.depth option or by using the related model's serializer instead of a RelatedField.

As @xleon said in his comment using URLs as keys makes it easier for other developers to understand your API.