frappe-api

# Frappe REST API Development

Create secure, well-documented REST API endpoints for Frappe Framework v15 following best practices for authentication, permission checking, and input validation.

## When to Use

- Building custom REST API endpoints
- Exposing service layer methods via HTTP
- Creating public/private API routes
- Implementing webhook handlers
- Building integrations with external systems

## Arguments

```
/frappe-api <endpoint_name> [--doctype <doctype>] [--public]
```

**Examples:**
```
/frappe-api get_dashboard_stats
/frappe-api create_order --doctype "Sales Order"
/frappe-api webhook_handler --public
```

## Procedure

### Step 1: Gather API Requirements

Ask the user for:

1. **Endpoint Name** (snake_case, e.g., `get_dashboard_stats`)
2. **HTTP Methods** supported (GET, POST, PUT, DELETE)
3. **Authentication Type:**
   - Token (API Key + Secret)
   - Session (Cookie-based)
   - OAuth 2.0
   - Public (no auth required - use sparingly)
4. **Parameters** - Input parameters with types
5. **Related DocType** (if applicable)
6. **Allowed Roles** (who can access this endpoint)

### Step 2: Design API Contract

Create the API specification:

```yaml
Endpoint: /api/method/<app>.<module>.api.<endpoint_name>
Methods: GET, POST
Auth: Token | Session
Rate Limit: 100 req/min (if applicable)

Parameters:
  - name: param1
    type: string
    required: true
    description: Description of param1
  - name: param2
    type: integer
    required: false
    default: 10

Response:
  200:
    description: Success
    schema:
      message: object
  400:
    description: Validation Error
  403:
    description: Permission Denied
```

### Step 3: Generate API Module Structure

Create `<app>/<module>/api/<endpoint_name>.py`:

```python
"""
<Endpoint Name> API

<Brief description of what this API does>

Endpoints:
    GET/POST /api/method/<app>.<module>.api.<endpoint_name>.<method_name>

Authentication:
    Token: Authorization: token api_key:api_secret
    Session: Cookie