frappe-api-handler_skill

Overview

This skill creates secure, efficient custom API endpoints and whitelisted methods for Frappe applications. It provides patterns for authenticated and public methods, REST-style handlers (GET/POST/PUT/DELETE), file uploads, bulk operations, pagination, input validation, error handling, and authentication. Use it to expose Frappe functionality safely to external systems or build REST APIs for your app.

How this skill works

The skill generates and documents Python methods decorated with frappe.whitelist() that become accessible via /api/method/{app}.{module}.{file}.{method}. It includes patterns for allow_guest and permission checks, parses JSON inputs, validates and sanitizes data, logs errors, and returns consistent response shapes. Common helpers cover pagination, file uploads, bulk creates, and API key or token authentication.

When to use it

• You need custom REST endpoints for a Frappe app
• You must whitelist Python methods for API access
• You are integrating external systems or third-party services
• You need secure file uploads or bulk data operations
• You want standard patterns for pagination, validation, and error handling

Best practices

• Always validate and sanitize incoming data before processing
• Check permissions with frappe.has_permission() and throw on denial
• Return consistent success/error payloads and use HTTP status codes where possible
• Log unexpected errors with frappe.log_error() and avoid exposing stack traces
• Version public APIs and consider rate limiting for guest endpoints

Example use cases

• Expose customer details via an authenticated whitelisted method for a mobile app
• Create sales orders from an external system using a POST handler that parses items and submits the document
• Provide paginated product lists with filters for a storefront or analytics service
• Accept file uploads tied to a document using save_file and return file metadata
• Run bulk create operations for migrating data or batch imports with error reporting