Complete Guide to the Django Services and Repositories Design Pattern with the Django REST Framework

INSTALLED_APPS = [
    "rest_framework",
    "apps.posts",
    "apps.comments",
...

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.title

from apps.posts.models import Post


class Comment(models.Model):
    post = models.ForeignKey(Post, related_name="comments", on_delete=models.CASCADE)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.content[:20]

from rest_framework import generics
from ..serializers import PostSerializer
from ..services.post_service import PostService

# API view for listing all posts and creating a new post.
# Utilizes Django REST Framework's ListCreateAPIView for listing and creating resources.
class PostListCreateAPIView(generics.ListCreateAPIView):
    serializer_class = PostSerializer  # Defines the serializer class used for converting model instances to JSON and vice versa.

    # Fetches all posts from the database.
    # `get_queryset` method specifies the queryset for listing posts.
    def get_queryset(self):
        return (
            PostService.get_all_posts()
        )  # Delegates the database query to the PostService layer.

    # Handles the creation of a new post.
    # `perform_create` is called after validation of the serializer.
    def perform_create(self, serializer):
        # Creates a new post using validated data from the serializer.
        PostService.create_post(
            serializer.validated_data
        )  # Uses PostService to handle creation logic.

# API view for retrieving, updating, and deleting a specific post.
# Extends RetrieveUpdateDestroyAPIView for detailed operations on a single resource.
class PostRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
    serializer_class = PostSerializer  # Specifies the serializer class for retrieving, updating, and deleting resources.

    # Retrieves a post object based on the provided post_id.
    # `get_object` method returns the post instance for the specified post_id.
    def get_object(self):
        post_id = self.kwargs.get("post_id")  # Extracts post_id from the URL kwargs.
        post = PostService.get_post_by_id(
            post_id
        )  # Fetches the post using PostService.
        if post is None:
            raise NotFound(
                "Comment not fund"
            )  # Raises a 404 error if the post does not exist.
        return post  # Returns the post instance.

    # Updates an existing post instance.
    # `perform_update` is called after the serializer's data is validated.
    def perform_update(self, serializer):
        post_id = self.kwargs["post_id"]  # Extracts post_id from the URL kwargs.
        # Updates the post with new data.
        PostService.update_post(
            serializer.validated_data, post_id
        )  # Delegates the update logic to PostService.

    # Deletes a post instance.
    # `perform_destroy` is called to delete the specified post.
    def perform_destroy(self, instance):
        post_id = self.kwargs["post_id"]  # Extracts post_id from the URL kwargs.
        # Deletes the post using PostService.
        PostService.delete_post(post_id)  # Delegates the deletion logic to PostService.

from django.views.generic import ListView, DetailView
from ..models import Post
from ..services.post_service import PostService

# Class-based view for listing all posts in the web interface.
# Utilizes Django's ListView to handle displaying a list of posts.
class PostListView(ListView):
    model = Post  # Specifies the model to be used in the view.
    template_name = (
        "posts/post_list.html"  # Path to the template for rendering the list of posts.
    )
    context_object_name = "posts"  # Context variable name to be used in the template.

    # Overrides the default get_queryset method to fetch all posts from the service layer.
    def get_queryset(self):
        return (
            PostService.get_all_posts()
        )  # Delegates the database query to the PostService.

# Class-based view for displaying the details of a single post.
# Utilizes Django's DetailView to handle displaying detailed information of a single post.
class PostDetailView(DetailView):
    model = Post
    template_name = "posts/post_detail.html"
    context_object_name = "post"

    # Overrides the default get_object method to fetch a specific post based on post_id.
    def get_object(self, queryset=None):
        post_id = self.kwargs.get("post_id")  # Extracts post_id from the URL kwargs.
        return PostService.get_post_by_id(
            post_id
        )  # Fetches the post using the PostService.

from rest_framework import generics
from ..serializers import CommentSerializer
from ..services.comment_service import CommentService
from rest_framework.exceptions import NotFound

class CommentListCreateAPIView(generics.ListCreateAPIView):
    serializer_class = CommentSerializer

    def get_queryset(self):
        # Retrieve the 'post_id' from the URL kwargs. This ID is used to filter comments related to a specific post.
        post_id = self.kwargs.get("post_id")
        # Fetch comments related to the given post ID using the CommentService. The repository layer handles actual data fetching.
        return CommentService.get_comments_by_post_id(post_id)

    def perform_create(self, serializer):
        # Retrieve the 'post_id' from the URL kwargs. This ID is used to associate the new comment with a specific post.
        post_id = self.kwargs.get("post_id")
        # Create a new comment for the specified post using the CommentService. The service layer handles data manipulation.
        CommentService.create_comment(serializer.validated_data, post_id)

class CommentRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
    serializer_class = CommentSerializer

    def get_object(self):
        # Retrieve the 'post_id' and 'comment_pk' from the URL kwargs.
        # 'post_id' is used to ensure the comment belongs to the post, while 'comment_pk' identifies the specific comment.
        post_id = self.kwargs.get("post_id")
        comment_id = self.kwargs.get("comment_pk")
        # Fetch the specific comment for the given post ID and comment ID using the CommentService.
        # Raise a 404 error if the comment is not found.
        comment = CommentService.get_comment_by_post_and_id(post_id, comment_id)
        if comment is None:
            raise NotFound("Comment not fund")
        return comment

    def perform_update(self, serializer):
        # Retrieve the 'comment_pk' from the URL kwargs for updating the specific comment.
        comment_id = self.kwargs["comment_pk"]
        # Update the specified comment using the CommentService. The service layer handles data manipulation.
        CommentService.update_comment(serializer.validated_data, comment_id)

    def perform_destroy(self, instance):
        # Retrieve the 'comment_pk' from the URL kwargs for deleting the specific comment.
        comment_id = self.kwargs["comment_pk"]
        # Delete the specified comment using the CommentService. The service layer handles data manipulation.
        CommentService.delete_comment(comment_id)

from django.views.generic import ListView, DetailView
from ..models import Comment
from ..services.comment_service import CommentService

class CommentListView(ListView):
    model = Comment
    template_name = "comments/comment_list.html"
    context_object_name = "comments"

    def get_queryset(self):
        # Extract 'post_id' from URL parameters to fetch comments associated with a specific post.
        post_id = self.kwargs.get("post_id")
        # Use the CommentService to retrieve comments for the specified post.
        # The service layer handles data access logic, keeping the view simple.
        return CommentService.get_comments_by_post_id(post_id)

    def get_context_data(self, **kwargs):
        # Get the default context from the parent class and add additional context for 'post_id'.
        context = super().get_context_data(**kwargs)
        # Include 'post_id' in the context so it can be used in the template.
        # This is necessary for rendering links or forms related to the post.
        context["post_id"] = self.kwargs.get("post_id")
        return context

class CommentDetailView(DetailView):
    model = Comment
    template_name = "comments/comment_detail.html"
    context_object_name = "comment"

    def get_object(self, queryset=None):
        # Extract 'post_id' and 'comment_id' from URL parameters to retrieve a specific comment for a post.
        post_id = self.kwargs.get("post_id")
        comment_id = self.kwargs.get("comment_id")
        # Use the CommentService to retrieve the specific comment based on 'post_id' and 'comment_id'.
        # If the comment is not found, `CommentService.get_comment_by_post_and_id` will return None.
        # In this case, a 404 error will be raised automatically by the `DetailView` if the object is not found.
        return CommentService.get_comment_by_post_and_id(post_id, comment_id)

from ..models import Post

class PostRepository:
    # Fetch all posts from the database
    @staticmethod
    def get_all_posts():
        return Post.objects.all()

    # Fetch a specific post by its primary key (ID)
    @staticmethod
    def get_post_by_id(post_id):
        return Post.objects.get(pk=post_id)

    # Create a new post with the provided data
    @staticmethod
    def create_post(data):
        return Post.objects.create(**data)

    # Update an existing post with the provided data
    @staticmethod
    def update_post(data, post_id):
        post = Post.objects.get(pk=post_id)
        for attr, value in data.items():
            setattr(post, attr, value)  # Dynamically update each attribute
        post.save()
        return post

    # Delete a post by its primary key (ID)
    @staticmethod
    def delete_post(post_id):
        post = Post.objects.get(pk=post_id)
        post.delete()

from ..models import Comment

class CommentRepository:
    @staticmethod
    def get_comments_by_post_id(post_id):
        # Retrieve all comments associated with a specific post_id
        return Comment.objects.filter(post_id=post_id)

    @staticmethod
    def get_comment_by_post_and_id(post_id, comment_id):
        # Retrieve a specific comment by post_id and comment_id
        try:
            return Comment.objects.get(post_id=post_id, id=comment_id)
        except Comment.DoesNotExist:
            # Return None if no comment is found
            return None

    @staticmethod
    def create_comment(data, post_id):
        # Create a new comment associated with a specific post_id
        return Comment.objects.create(post_id=post_id, **data)

    @staticmethod
    def update_comment(data, comment_id):
        # Update an existing comment identified by comment_id
        comment = Comment.objects.get(pk=comment_id)
        for attr, value in data.items():
            setattr(comment, attr, value)
        comment.save()
        return comment

    @staticmethod
    def delete_comment(comment_id):
        # Delete an existing comment identified by comment_id
        comment = Comment.objects.get(pk=comment_id)
        comment.delete()

from ..repositories.post_repository import PostRepository

class PostService:
    @staticmethod
    def get_all_posts():
        # Retrieve all posts from the repository
        return PostRepository.get_all_posts()

    @staticmethod
    def get_post_by_id(post_id):
        # Retrieve a post by its ID from the repository
        return PostRepository.get_post_by_id(post_id)

    @staticmethod
    def create_post(data):
        # Create a new post with the given data
        return PostRepository.create_post(data)

    @staticmethod
    def update_post(data, post_id):
        # Update an existing post with the given data
        return PostRepository.update_post(data, post_id)

    @staticmethod
    def delete_post(post_id):
        # Delete a post by its ID from the repository
        return PostRepository.delete_post(post_id)

from ..repositories.comment_repository import CommentRepository

class CommentService:
    @staticmethod
    def get_comments_by_post_id(post_id):
        # Delegate the task of retrieving comments by post_id to the repository layer
        return CommentRepository.get_comments_by_post_id(post_id)

    @staticmethod
    def get_comment_by_post_and_id(post_id, comment_id):
        # Delegate the task of retrieving a specific comment by post_id and comment_id to the repository layer
        return CommentRepository.get_comment_by_post_and_id(post_id, comment_id)

    @staticmethod
    def create_comment(data, post_id):
        # Delegate the task of creating a new comment to the repository layer
        return CommentRepository.create_comment(data, post_id)

    @staticmethod
    def update_comment(data, comment_id):
        # Delegate the task of updating an existing comment to the repository layer
        return CommentRepository.update_comment(data, comment_id)

    @staticmethod
    def delete_comment(comment_id):
        # Delegate the task of deleting a comment to the repository layer
        return CommentRepository.delete_comment(comment_id)

from rest_framework import serializers
from .models import Post

# Serializer for the Post model
# This class is responsible for converting Post instances into JSON data and validating incoming data for creating or updating posts.
class PostSerializer(serializers.ModelSerializer):

    # Meta class specifies the model and fields to be used by the serializer.
    class Meta:
        model = Post  # The model associated with this serializer. It tells DRF which model the serializer will be handling.
        fields = "__all__"  # Specifies that all fields from the model should be included in the serialization and deserialization process.

from rest_framework import serializers
from .models import Comment

# CommentSerializer is a ModelSerializer that automatically creates fields and methods for the Comment model.
class CommentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Comment  # The model that this serializer will be based on.
        fields = "__all__"  # Automatically include all fields from the Comment model.

from django.urls import path
from ..views.api_views import PostListCreateAPIView, PostRetrieveUpdateDestroyAPIView
from ...comments.views.api_views import (
    CommentListCreateAPIView,
    CommentRetrieveUpdateDestroyAPIView,
)

urlpatterns = [
    # Route for listing all posts or creating a new post
    path("", PostListCreateAPIView.as_view(), name="post-list-create"),
    # Route for retrieving, updating, or deleting a specific post by post_id
    path(
        "<int:post_id>/",
        PostRetrieveUpdateDestroyAPIView.as_view(),
        name="post-retrieve-update-destroy",
    ),
    # Route for listing all comments for a specific post or creating a new comment for that post
    path(
        "<int:post_id>/comments/",
        CommentListCreateAPIView.as_view(),
        name="post-comment-create",
    ),
    # Route for retrieving, updating, or deleting a specific comment by comment_pk for a specific post
    path(
        "<int:post_id>/comments/<int:comment_pk>/",
        CommentRetrieveUpdateDestroyAPIView.as_view(),
        name="post-comment-retrieve-update-destroy",
    ),
]

from django.urls import path
from ..views.web_views import PostListView, PostDetailView
from ...comments.views.web_views import CommentListView, CommentDetailView

urlpatterns = [
    # Route for listing all posts.
    # The URL is "web/posts/", and it maps to PostListView to display a list of all posts.
    path("", PostListView.as_view(), name="post-list"),
    # Route for displaying details of a specific post identified by post_id.
    # The URL is "web/posts/<post_id>/", and it maps to PostDetailView to display details of a single post.
    path("<int:post_id>/", PostDetailView.as_view(), name="post-detail"),
    # Route for listing all comments for a specific post identified by post_id.
    # The URL is "web/posts/<post_id>/comments", and it maps to CommentListView to display a list of comments for the given post.
    path(
        "<int:post_id>/comments",
        CommentListView.as_view(),
        name="post-comments",
    ),
    # Route for displaying details of a specific comment identified by comment_id for a specific post.
    # The URL is "web/posts/<post_id>/comments/<comment_id>/", and it maps to CommentDetailView to display details of a single comment.
    path(
        "<int:post_id>/comments/<int:comment_id>/",
        CommentDetailView.as_view(),
        name="post-comment-detail",
    ),
]

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("posts/", include("apps.posts.urls.web_urls")),
    path("api/posts/", include("apps.posts.urls.api_urls")),
]

You can repeat these steps to create as many posts and comments as you want.

Also, in this same Django REST API interface you can edit posts or comments or delete them.

2. **See the details of a specific post:**

    * **URL:**`/posts/{post_id}/`

3. **See comments on a specific post:**

    * **URL:**`/posts/{post_id}/comments/`

4. **View the details of a comment on a specific post:**

    * **URL:**`/posts/{post_id}/comments/{comment_id}/`

* **Clarity and Organisation:** The code is organised so that each class and function has a single, clearly defined responsibility. This makes the code easier to understand and maintain.

* **Maintainability:** When the business logic changes, only the services need to be modified, while the repositories remain unchanged. This reduces the number of changes and the risk of introducing errors.

* **Team Collaboration:** In a development team, different members can work at different layers (e.g. one on services and one on repositories) without interfering with each other, facilitating collaboration and integration.

* **Duplication Reduction:** By having business logic in services and data access in repositories, we avoid repeating code in multiple places, making the code more DRY (Don't Repeat Yourself).

* **Consistency:** Reusing the same code in different parts of the application ensures that the same logic and rules are followed everywhere, which increases consistency and reduces errors.

* **Ease of Update:** If you need to change the way data is accessed or business logic is implemented, you only need to update the corresponding repository or service. The other parts of the application that depend on them will automatically benefit from the changes.

* **Unit testing:** By having business logic in services and data access in repositories, it is easier to create unit tests for each component independently. This makes it possible to quickly detect errors and ensure that each part works correctly.

* **Mocks and Stubs:** During testing, it is easy to use mocks and stubs to simulate the behaviour of repositories or services. This allows testing business logic without relying on the database or other external services.

* **Reduced Testing Complexity:** By having clear and well-defined responsibilities, testing becomes less complex and more specific. This improves test coverage and software reliability.

* **Code Evolution:** When you need to add new functionality, it is easy to extend existing services and repositories without affecting the rest of the application. This allows the code to evolve in a controlled and safe way.

* **Easy Refactoring:** If you identify an improvement in the code structure or business logic implementation, it is easy to refactor services and repositories without great risk. The separation of responsibilities makes it easy to identify which parts of the code need to be changed.

* **Adaptability to New Technologies:** If at some point you decide to change the persistence technology (for example, from a SQL database to a NoSQL one), you only need to modify the repositories without affecting the business logic implemented in the services.