frappe-api-handler

Generate Frappe API Handler

Create secure API endpoints for Frappe applications. Supports both standard Frappe and microservices.

When to Use

• Creating custom API endpoints
• Building REST APIs
• Creating whitelisted methods
• Building microservice endpoints

Core Patterns

1. Standard Frappe API

@frappe.whitelist()
def get_customer_details(customer_name):
    if not frappe.has_permission("Customer", "read"):
        frappe.throw(_("Not permitted"), frappe.PermissionError)
    
    customer = frappe.get_doc("Customer", customer_name)
    return {
        "name": customer.name,
        "customer_name": customer.customer_name,
        "email": customer.email_id
    }

@frappe.whitelist(allow_guest=True)
def public_api():
    return {"message": "Public data"}

2. REST Patterns

GET with pagination:

@frappe.whitelist()
def get_items(filters=None, limit=20, page=1):
    filters = frappe.parse_json(filters) if isinstance(filters, str) else filters or {}
    if not frappe.has_permission("Item", "read"):
        frappe.throw(_("Not permitted"), frappe.PermissionError)
    
    items = frappe.get_all("Item", filters=filters, limit=limit, limit_start=(page-1)*limit)
    return {"items": items, "total": frappe.db.count("Item", filters=filters)}

POST:

@frappe.whitelist()
def create_order(order_data):
    data = frappe.parse_json(order_data) if isinstance(order_data, str) else order_data
    if not data.get("customer"):
        frappe.throw(_("Customer is required"))
    
    so = frappe.get_doc({"doctype": "Sales Order", **data})
    so.insert()
    return {"success": True, "name": so.name}

PUT/DELETE: Similar pattern - get doc, update/delete, return result

3. Microservice API

@app.secure_route('/api/customers', methods=['GET'])
def list_customers(user):
    tenant_id = get_current_tenant_id()
    app.set_tenant_id(tenant_id)
    customers = app.tenant_db.get_all('Customer', filters=request.args.get('filters', {}))
    return {"data": customers}

@app.secure_route('/api/customers', methods=['POST'])
def create_customer(user):
    tenant_id = get_current_tenant_id()
    app.set_tenant_id(tenant_id)
    customer = app.tenant_db.insert_doc('Customer', request.json)
    return {"success": True, "data": customer.as_dict()}, 201

4. Error Handling

@frappe.whitelist()
def api_with_errors(param):
    try:
        if not param:
            frappe.throw(_("Required"), frappe.ValidationError)
        return {"success": True, "data": process(param)}
    except frappe.ValidationError as e:
        return {"success": False, "error": str(e), "code": "VALIDATION_ERROR"}, 400
    except frappe.PermissionError as e:
        return {"success": False, "error": str(e), "code": "PERMISSION_ERROR"}, 403
    except frappe.DoesNotExistError as e:
        return {"success": False, "error": str(e), "code": "NOT_FOUND"}, 404
    except Exception as e:
        frappe.log_error(f"API error: {e}")
        return {"success": False, "error": "Internal error", "code": "INTERNAL_ERROR"}, 500

5. Authentication

Session-based:

@frappe.whitelist()
def authenticated_api():
    return {"user": frappe.session.user}

API Key:

@frappe.whitelist()
def api_key_auth():
    api_key = frappe.get_request_header("X-API-Key")
    if not api_key:
        frappe.throw(_("API Key required"), frappe.AuthenticationError)
    # Validate key
    return {"authenticated": True}

Key Patterns

1. Always check permissions with frappe.has_permission()
2. Parse JSON strings with frappe.parse_json()
3. Return proper HTTP status codes
4. Validate input before processing
5. Use app.tenant_db in microservices
6. Log errors with frappe.log_error()

Best Practices

• Use @frappe.whitelist() decorator
• Check permissions before operations
• Validate all input
• Use frappe._() for translatable messages
• Consistent response format
• Document with docstrings

Remember: This skill is model-invoked. Claude will use it autonomously when detecting API development tasks.

Decision Tree & Reference

Cross-package reference from frappe-core-api and frappe-syntax-whitelisted: where to expose logic, how clients call Frappe, and rules that extend the patterns above.

Decision tree: API surfaces (integrations & clients)

What do you need?
├── CRUD on documents (external client)
│   ├── v14: REST /api/resource/{doctype}
│   └── v15+: REST /api/v2/document/{doctype} (new) or /api/resource/ (still works)
│
├── Call custom server logic (external client)
│   └── RPC: POST /api/method/{dotted.path.to.function}
│
├── Notify external systems on document events
│   └── Webhooks (configured in UI or via DocType)
│
├── Client-side calls (JavaScript in Frappe desk)
│   ├── frappe.xcall() — async/await (RECOMMENDED)
│   └── frappe.call() — callback/promise pattern
│
└── Authentication method?
    ├── Server-to-server integration → Token Auth (RECOMMENDED)
    ├── Third-party app / mobile → OAuth 2.0
    ├── Browser session (short-lived) → Session/Cookie Auth
    └── Quick scripting / testing → Token Auth

Decision tree: @frappe.whitelist() design

What kind of endpoint?
|
+-- Standalone API (utility, integration, dashboard)?
|   --> @frappe.whitelist() on a module-level function
|   --> Call via: frappe.call('myapp.api.function')
|   --> URL: /api/method/myapp.api.function
|
+-- Document-specific action?
|   --> @frappe.whitelist() on a Document class method
|   --> Call via: frm.call('method_name')
|   --> URL: /api/method/run_doc_method (internal)
|
+-- Server Script (no-code)?
    --> Use Server Script DocType instead (no decorator needed)

Who may call the API?
|
+-- Anyone (including guests)?
|   --> allow_guest=True + thorough input validation + rate limiting
|
+-- Logged-in users only?
    +-- Specific role? --> frappe.only_for("RoleName")
    +-- DocType-level? --> frappe.has_permission(doctype, ptype, throw=True)
    +-- Document-level? --> frappe.has_permission(doctype, ptype, doc, throw=True)

Which HTTP methods?
|
+-- Read only? --> methods=["GET"]
+-- Write only? --> methods=["POST"]
+-- Both? --> methods=["GET","POST"] or default

Quick reference tables

Module-level RPC / Desk entrypoint: /api/method/{dotted.module.path.function_name} (returns JSON with message carrying the Python return value on success.)

RPC decorator option	Effect	Notes
allow_guest=True	No login required	ALWAYS tighten validation + consider @rate_limit
xss_safe=True	Skips XSS escaping	NEVER without fully trusted/sanitized output
methods=[...]	Limits HTTP verbs	e.g. ["POST"] for mutations
force_types=True	[v15+] Require param annotations	Missing annotations → FrappeTypeError

REST operation	Method	v14	v15+ (v2)
List	GET	/api/resource/{doctype}	/api/v2/document/{doctype}
Create	POST	/api/resource/{doctype}	/api/v2/document/{doctype}
Read	GET	/api/resource/{doctype}/{name}	/api/v2/document/{doctype}/{name}
Update	PUT	/api/resource/{doctype}/{name}	PATCH /api/v2/document/{doctype}/{name}
Delete	DELETE	/api/resource/{doctype}/{name}	DELETE /api/v2/document/{doctype}/{name}

Code	Typical meaning
200	Success
400	Bad request / validation
401	Not authenticated
403	Authenticated but not permitted
404	Missing doc/resource
417	frappe.throw / expectation failed
429	Rate limited
500	Unhandled server error

frappe.client RPC (Desk / token)	Purpose
get_value, get_list, get	Read
insert, save, submit, cancel, delete	Writes / workflow
get_count	Count with filters

List query params clients often send: fields, filters, or_filters, order_by, limit_start, limit_page_length (limit alias on v15+), optional debug.

ALWAYS / NEVER (additive — extends Key Patterns above)

• ALWAYS send Accept: application/json when calling Frappe REST from scripts or services (otherwise responses may be HTML).
• ALWAYS use parameterized DB access — NEVER build SQL by interpolating user input.
• ALWAYS set a timeout (e.g. timeout=30) on outbound requests to third parties.
• ALWAYS keep secrets in frappe.conf or environment variables — NEVER hardcode keys in repo.
• ALWAYS paginate list-style API responses intended for arbitrary-sized data.
• ALWAYS verify webhook HMAC (X-Frappe-Webhook-Signature) when exposing inbound webhook receivers.
• NEVER use allow_guest=True on endpoints that change data or privileged state without extra gates (validation + rate limit + minimal surface).
• NEVER log credentials or PCI/secret-bearing payloads.
• NEVER use Administrator API keys for integrations — dedicate least-privilege API users.
• NEVER rely on @frappe.whitelist() alone for authorization — treat login as authentication only; still enforce frappe.has_permission / frappe.only_for as needed (see Key Patterns above).
• NEVER return raw stack traces to API clients — use frappe.log_error and a safe user-facing message.
• NEVER use ignore_permissions=True without an explicit preceding role/security guard.
• ALWAYS apply @rate_limit on guest-visible endpoints to reduce abuse.

Critical Rules (sources — condensed)

From frappe-core-api: prefer token auth for integrations; store API secrets immediately when generated (shown once); session cookies expire (~3 days) — not for long-lived integrations; set Webhook secrets; use Jinja2 conditions on webhook conditions; outbound integration calls need timeouts and safe credential storage.

From frappe-syntax-whitelisted: HTTP parameters arrive as strings — coerce types and frappe.parse_json for JSON blobs; Desk callers should JSON.stringify complex frappe.call args; frappe.form_dict for dynamic param maps; [v15+] optional force_types and site hook require_type_annotated_api_methods enforce annotations; frappe.local.response["http_status_code"] for non-default RPC HTTP status where applicable.