Responses¶

Define stable response contracts so frontend and integrators can rely on one predictable envelope.

Prerequisites¶

API Class scaffolded and routed.
config/responses.csv exists in the project.

Implementation¶

Below are practical examples and usage instructions for each response helper function in the Response Kit. These functions create standardized JSON responses with consistent status codes, messages, and data envelopes across Django Rest API endpoints.

1. Json Response¶

Return standardized JSON API envelope using response-code metadata.

Usage:

from django_mindoff.components.response_kit import mo_response_kit

return mo_response_kit.json_response(
    code="SUCCESS",
    category="success",
    data={"id": "abc123"},
)

Parameters:

code: Response code defined in config/responses.csv.
category: UI/semantic category for clients. One of: danger, warning, info, success.
data: Response payload body.
exception: Optional exception object for debug/log context.

Behavior:

HTTP status and message metadata are resolved from responses.csv.
Unknown/empty code falls back to UNEXPECTED_ERR.

2. File Response¶

Return downloadable file response from file path or in-memory bytes.

Usage:

from django_mindoff.components.response_kit import mo_response_kit
import io

return mo_response_kit.file_response("exports/orders.csv")

# OR
buffer = io.BytesIO(b"id,total\n1,30\n")
return mo_response_kit.file_response(
    buffer,
    filename="orders.csv",
    content_type="text/csv",
)

Parameters:

file_obj: File path (str) or in-memory bytes (io.BytesIO).
filename: Optional download filename. Auto-generated for BytesIO if omitted.
content_type: Optional MIME type override.

3. Text Response¶

Return plain text HTTP response.

Usage:

from django_mindoff.components.response_kit import mo_response_kit
return mo_response_kit.text_response("ok", status_code=200)

4. Html Response¶

Return HTML HTTP response.

Usage:

from django_mindoff.components.response_kit import mo_response_kit
return mo_response_kit.html_response("<h1>Ready</h1>", status_code=200)

Core Concepts¶

1. Standard JSON Envelope¶

json_response(...) returns a consistent envelope:

{
    "status": "ok|fail|exception",
    "message": {
        "code": "SUCCESS",
        "title": "Success",
        "description": "Operation completed successfully.",
        "category": "success"
    },
    "data": {}
}

Envelope fields:

status: Derived from response code HTTP status (2xx -> ok, 4xx -> fail, 5xx -> exception).
message.code: Stable response code from responses.csv.
message.title and message.description: Human-readable values loaded from responses.csv.
message.category: One of danger, warning, info, success.
data: Payload body (object/list; defaults to [] when empty).

2. Response Codes¶

Response code definitions are loaded from:

config/responses.csv

Required headers:

code
title
description
http_status

Practical rules:

code is normalized to uppercase.
Duplicate codes are rejected during load.
http_status must be within 200..599.
If a code is missing/unknown, the handler falls back to UNEXPECTED_ERR.

Keep response codes centralized

The django-mindoff project ships with a standard set of response codes. Do not remove or alter the default codes as they are used by Mindoff's Core features. However, feel free to update their title, description, and http_status as the developer feels fit for the project.

Do not hardcode title/description in endpoint code. Add or update codes in config/responses.csv so behavior stays consistent across APIs.

Troubleshooting¶

Unknown Response code: '<CODE>'
Add the code to config/responses.csv or use an existing code.
Startup/load failures for responses file
Ensure config/responses.csv exists and includes required headers.
Unexpected status in JSON envelope
Verify http_status configured for the code in responses.csv.