Should Frappe's DocType REST API Follow More Consistent RESTful Conventions?

Frappe Framework
,
1

Hi everyone,

I’ve been building a SaaS platform using Frappe, and I appreciate how quickly DocTypes allow us to create data models, permissions, and CRUD APIs without implementing everything from scratch.

However, when building a production application that consumes these APIs from external clients, I find that handling API responses and errors consistently can require additional work.

I’d like to understand whether there are existing best practices for this or whether this is an area worth improving in the framework.

1. Consistent HTTP status codes

Should DocType endpoints consistently return appropriate HTTP status codes for common scenarios?

For example:

  • 200 OK for successful reads and updates.

  • 201 Created when a resource is created.

  • 204 No Content when a resource is successfully deleted without returning a body.

  • 400 Bad Request for malformed requests or invalid input.

  • 401 Unauthorized for unauthenticated requests.

  • 403 Forbidden for authenticated users without permission.

  • 404 Not Found when a requested resource does not exist.

  • 409 Conflict for conflicting operations.

  • 422 Unprocessable Content for semantically invalid input, where appropriate.

  • 500 Internal Server Error for unexpected server-side failures.

I understand that some of these distinctions depend on the operation and existing framework conventions. My question is whether Frappe aims to provide a consistent mapping across its generated endpoints and custom whitelisted methods.

2. Predictable error response bodies

Another challenge is handling errors consistently in frontend applications and third-party integrations.

Would it be beneficial for Frappe to provide a standardized error structure, such as:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The submitted data is invalid.",
    "details": [
      {
        "field": "email",
        "message": "A valid email address is required."
      }
    ]
  }
}

A consistent structure would make it easier for clients to distinguish validation errors, permission failures, missing resources, business rule violations, and unexpected server errors without writing custom parsing logic for different exceptions.

3. Internal server errors and exception handling

When an unexpected exception occurs, API consumers should receive a predictable HTTP status and a safe, machine-readable error response.

Detailed tracebacks and internal implementation details should remain available in server logs rather than being exposed to external clients in production.

Could the framework provide a consistent exception-to-HTTP-status mapping and a configurable error response format for both generated DocType endpoints and custom APIs?

4. Querying and extracting data

Although DocType endpoints support fields, filters, and pagination, complex data retrieval can sometimes require additional custom whitelisted methods.

Would improvements to filtering, field selection, relationship handling, and response consistency help reduce the amount of custom API code developers need to maintain?

5. My question to the community

Is there an established approach in Frappe for achieving these standards across all DocType endpoints, or does the recommended approach involve implementing a custom API layer for production applications?

I would also appreciate clarification on which of these behaviors are already supported by the current REST API v2 and which require custom implementation.

I believe more predictable HTTP semantics and error contracts would make Frappe easier to use as the backend for SaaS platforms, mobile applications, and external integrations.

Thanks!

2

Hi @sentic and welcome to the community

I hope someone does reply to you here

If not I feel the better place is for you to contribute improvements/suggestions at their github

Best of luck