Frappe API Development

Build secure, well-designed APIs using Frappe's REST and RPC patterns.

When to use

• Creating custom RPC endpoints (@frappe.whitelist)
• Building REST API integrations
• Implementing webhooks for external systems
• Setting up API authentication (token, OAuth)
• Exposing business logic to frontends

Inputs required

• API purpose (CRUD, action, integration)
• Authentication requirements (public, user, API key)
• Permission requirements per endpoint
• Request/response format expectations

Procedure

0) Choose API pattern

| Need | Pattern | |------|---------| | DocType CRUD | Use built-in REST API | | Custom action | RPC with @frappe.whitelist | | External callback | Webhook DocType | | Batch operations | Background job + status endpoint |

1) Built-in REST API (DocType CRUD)

Frappe provides automatic REST endpoints for all DocTypes:

# Create
POST /api/resource/Customer
{"customer_name": "Acme Corp"}

# Read
GET /api/resource/Customer/CUST-001

# Update
PUT /api/resource/Customer/CUST-001
{"customer_name": "Acme Corporation"}

# Delete
DELETE /api/resource/Customer/CUST-001

# List with filters
GET /api/resource/Customer?filters=[["status","=","Active"]]

2) Custom RPC endpoints

Create whitelisted methods in your app:

# my_app/api.py
import frappe

@frappe.whitelist()
def process_order(order_id, action):
    """Process an order with the given action."""
    # Always verify permissions
    doc = frappe.get_doc("Sales Order", order_id)
    if not frappe.has_permission("Sales Order", "write", doc):
        frappe.throw("Not permitted", frappe.PermissionError)
    
    # Business logic
    if action == "approve":
        doc.status = "Approved"
        doc.save()
    
    return {"status": "success", "order": doc.name}

@frappe.whitelist(allow_guest=True)
def public_endpoint():
    """Public endpoint - no auth required."""
    return {"message": "Hello, World!"}

Call via:

POST /api/method/my_app.api.process_order
{"order_id": "SO-001", "action": "approve"}

3) Implement authentication

API Key + Secret (recommended for integrations):

# Header format
Authorization: token api_key:api_secret

Bearer Token:

Authorization: Bearer <token>

Session (for logged-in users): Automatic via cookies.

4) Permission checks

ALWAYS check permissions in RPC methods:

@frappe.whitelist()
def sensitive_action(docname):
    doc = frappe.get_doc("My DocType", docname)
    
    # Check document-level permission
    if not frappe.has_permission("My DocType", "write", doc):
        frappe.throw("Not permitted", frappe.PermissionError)
    
    # Check role-based permission
    if "Manager" not in frappe.get_roles():
        frappe.throw("Manager role required")
    
    # Proceed with action
    ...

5) Input validation

@frappe.whitelist()
def create_item(name, qty, price):
    # Validate required fields
    if not name:
        frappe.throw("Name is required")
    
    # Validate types
    qty = frappe.utils.cint(qty)
    price = frappe.utils.flt(price)
    
    # Validate ranges
    if qty <= 0:
        frappe.throw("Quantity must be positive")
    
    # Proceed
    ...

6) Response format

Success response:

return {
    "status": "success",
    "data": {...}
}

Error handling:

# User-facing error
frappe.throw("Validation failed", title="Error")

# Permission error
frappe.throw("Not allowed", frappe.PermissionError)

# Standard exceptions become {"exc_type": "...", "exc": "..."}

7) Background jobs for long operations

@frappe.whitelist()
def start_export(filters):
    job = frappe.enqueue(
        "my_app.jobs.run_export",
        filters=filters,
        queue="long",
        timeout=600
    )
    return {"job_id": job.id}

@frappe.whitelist()
def check_job_status(job_id):
    from frappe.utils.background_jobs import get_job
    job = get_job(job_id)
    return {"status": job.get_status()}

Verification

• [ ] Endpoint responds correctly to valid requests
• [ ] Permission errors returned for unauthorized access
• [ ] Input validation rejects invalid data
• [ ] Error responses are structured and helpful
• [ ] Run: bench --site <site> console → test endpoint manually

Failure modes / debugging

• Method not found: Check module path in URL matches Python path
• Permission denied: Verify @frappe.whitelist() decorator and user permissions
• CSRF error: Use proper auth headers for API calls
• 500 error: Check error logs: bench --site <site> show-log

Escalation

• For OAuth integration, see references/oauth.md
• For webhook patterns, see references/webhooks.md
• For rate limiting, see references/rate-limiting.md

References

• references/rest-api.md - REST API details
• references/authentication.md - Auth patterns
• references/permissions.md - Permission system
• references/webhooks.md - Outbound webhooks

Guardrails

• Always validate input: Never trust client data; validate type, length, and format server-side
• Use permission callbacks: Check frappe.has_permission() explicitly in whitelisted methods
• Sanitize user input: Use frappe.db.escape() for SQL, avoid eval() and dynamic code execution
• Handle rate limiting: Implement rate limits for public APIs to prevent abuse
• Return structured errors: Use frappe.throw() with proper HTTP status codes

Common Mistakes

| Mistake | Why It Fails | Fix | |---------|--------------|-----| | Missing @frappe.whitelist() | Method returns "Method not found" error | Add decorator to expose method via API | | Using GET for mutations | Violates REST conventions, CSRF issues | Use POST/PUT/DELETE for data changes | | Not handling errors | 500 errors expose stack traces | Wrap in try/except, use frappe.throw() | | Exposing sensitive data | Security breach | Filter response fields, check permissions | | Missing allow_guest=True | Public endpoints return 403 | Add @frappe.whitelist(allow_guest=True) for unauthenticated access | | SQL injection in queries | Database compromise | Use Query Builder or frappe.db.escape() |