api-development

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

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"}