error_handling

Here's an example error_handling.md for the django-success-response documentation:

Error Handling

django-success-response provides a standardized way of handling both successful and error responses in your Django REST Framework views. It allows you to format error responses in a consistent structure, making it easier to handle errors across your API.

1. Customizing Error Responses

By default, errors in your API responses are structured as follows:

{
    "success": false,
    "result": {
        "detail": "error message"
    }
}

This structure helps maintain consistency in your API responses, making it clear whether the response is a success or an error, and what the error message is.

2. Using `SuccessResponse` for Error Handling

You can explicitly specify an error response by setting the success field to false and providing the appropriate error message in the result field.

Example: Error Response

from success_response.response import SuccessResponse
from rest_framework.views import APIView


class MyView(APIView):
    @staticmethod
    def get(request):
        # Simulating an error
        data = {'detail': 'An error occurred'}
        return SuccessResponse(data, success=False)

Result:

{
    "success": false,
    "result": {
        "detail": "An error occurred"
    }
}

3. Global Error Handling with Custom Exception Handler

You can globally customize error handling for all views in your Django project by updating the EXCEPTION_HANDLER setting in your settings.py file.

In your settings.py, add the following configuration:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'success_response.views.success_exception_handler',
}

This ensures that all exceptions raised in your views are caught and formatted using the SuccessResponse structure.

4. Example: Handling Different Error Types

You can customize the error structure depending on the type of exception or error you want to return. For example, in a view, you can check for specific exceptions and provide custom messages:

from rest_framework.exceptions import NotFound, ValidationError
from success_response.response import SuccessResponse
from rest_framework.views import APIView

class MyView(APIView):
    @staticmethod
    def get(request):
        try:
            # Some operation that may raise an error
            raise ValidationError("This is a validation error.")
        except ValidationError as e:
            return SuccessResponse({'detail': str(e)}, success=False)
        except NotFound as e:
            return SuccessResponse({'detail': str(e)}, success=False)
        except Exception as e:
            return SuccessResponse({'detail': 'An unexpected error occurred.'}, success=False)

Result (Validation Error):

{
    "success": false,
    "result": {
        "detail": "This is a validation error."
    }
}

5. Example: Handling Database Errors

For errors such as database issues or missing objects, you can catch and format them as error responses using the SuccessResponse structure:

from django.core.exceptions import ObjectDoesNotExist
from success_response.response import SuccessResponse
from rest_framework.views import APIView

class MyView(APIView):
    @staticmethod
    def get(request):
        try:
            # Attempt to retrieve an object from the database
            obj = SomeModel.objects.get(id=1)
        except ObjectDoesNotExist:
            return SuccessResponse({'detail': 'Object not found'}, success=False)
        return SuccessResponse({'data': obj.name})

Result (Object Not Found Error):

{
    "success": false,
    "result": {
        "detail": "Object not found"
    }
}

6. Handling Validation Errors

For validation errors, Django REST Framework provides built-in validation mechanisms. You can catch and format those validation errors using SuccessResponse:

from success_response.exceptions import SuccessValidationError
from success_response.response import SuccessResponse
from rest_framework.views import APIView

class MyView(APIView):
    @staticmethod
    def post(request):
        # Simulate a validation error
        if 'key' not in request.data:
            raise SuccessValidationError({"detail":"Missing required field: 'key'"})
        
        return SuccessResponse({'message': 'Data received successfully'})