Documenting feature benefits & best practices

[Alex3917]

I think the documentation would be improved by more information on the benefits of each feature, rather than just how to implement it.

Before getting into examples, I'll briefly describe my personal use case for some context:

I got into DRF mainly because we wanted JWT auth for Django. We are building an API for our angular front end, but it's not going to be a public API (at first), so we don't necessarily get a ton of benefit from being able to serialize into formats other than JSON. We are using Django's ORM, but on some of our endpoints we're doing some complex validation and transformation of data coming from the client before we can store it.

Specific examples:

1. Serializers - there are dozens of pages of documentation on serializers, but only a couple paragraphs about the actual benefits. I'm trying trying to figure out the best practices on:

• When to use vs. not use serializers.
• More information on the benefits that serializers provide.
• Best practices and examples of endpoints that use DRF without serializers.

2. "Most of the time you're dealing with validation in REST framework you'll simply be relying on the default field validation, or writing explicit validation methods on serializer or field classes."

This could really be expanded into a paragraph or two. E.g. when should you rely on default field validation, vs. writing explicit validation methods.

3. How do serializer relationships correspond with model relationships? E.g. if I have two models with a relationship, do my serializers need to reflect that relationship? Can I have extra relationships between serializers that aren't in my models? If so, what are the benefits as opposed to having the relationship in the models.

Most of the docs and tutorial material assume that you're going to be on the 'happy path' of having a model and turning some of the fields on that model into an endpoint. And even if that's true for most of your endpoints, inevitably most apps are going to have some endpoints where you're going to need to do things that don't fit into this model. More guidance here on best practices would be super useful.

[Alex3917]

I also wanted to add that I think there needs to be more documentation on security best practices. Especially with a lot of the DRF magic, it's hard to know what endpoints are actually being exposed just by looking at the code, and I'm afraid that if I were to adopt these conventions then it would be too easy for myself or someone else to make a mistake and expose sensitive data. (So for now I'm sticking to the more explicit syntax everywhere.) I was also somewhat alarmed to discover that my docstrings for each endpoint were being publicly displayed to the user.

I think some high level documentation on the design decisions from a security perspective would be helpful, in terms of making it easier for folks to make good choices.

[tomchristie]

👍 Plenty of good stuff to consider here.

[thedrow]

@tomchristie I think we should work on that on the next sprint unless someone beats us to it.

[tomchristie]

I'll have to see how I'm doing on the day, but might be good sure.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.