Frappe REST API Guide | Manzoor Sofi

Introduction

One of Frappe's greatest strengths is its auto-generated REST API. Every DocType you create instantly gets a fully functional CRUD API without writing a single line of backend routing code.

Authentication

To communicate with the API securely, you should use Token-based authentication. First, generate an API Key and API Secret for your User in the Frappe Desk.

bash

# Pass the tokens in the Authorization header
curl -X GET http://yoursite.local/api/resource/Customer \
  -H "Authorization: token api_key:api_secret"

Standard CRUD Operations

Frappe provides RESTful routes for interacting with DocTypes.

1. Fetching a List of Records (GET)

You can fetch records, apply filters, and select specific fields.

javascript

// Using JavaScript fetch
const response = await fetch('http://yoursite.local/api/resource/Customer?fields=["name","customer_group"]&filters=[["customer_group","=","Commercial"]]', {
    method: 'GET',
    headers: {
        'Authorization': 'token api_key:api_secret'
    }
});
const data = await response.json();
console.log(data.data);

2. Fetching a Single Record (GET)

bash

# GET /api/resource/DocType/DocumentName
curl -X GET http://yoursite.local/api/resource/Customer/CUST-0001 \
  -H "Authorization: token api_key:api_secret"

3. Creating a Record (POST)

bash

curl -X POST http://yoursite.local/api/resource/Customer \
  -H "Authorization: token api_key:api_secret" \
  -H "Content-Type: application/json" \
  -d '{"customer_name": "New Tech Corp", "customer_group": "Commercial"}'

4. Updating a Record (PUT)

bash

curl -X PUT http://yoursite.local/api/resource/Customer/CUST-0001 \
  -H "Authorization: token api_key:api_secret" \
  -H "Content-Type: application/json" \
  -d '{"territory": "Global"}'

5. Deleting a Record (DELETE)

bash

curl -X DELETE http://yoursite.local/api/resource/Customer/CUST-0001 \
  -H "Authorization: token api_key:api_secret"

RPC Calls (Calling Whitelisted Methods)

If you need to execute custom business logic, you can call Python methods decorated with @frappe.whitelist().

python

# In your python file (my_app.api)
import frappe

@frappe.whitelist()
def ping_server(message):
    return f"Server received: {message}"

bash

# Calling the method via REST
curl -X POST http://yoursite.local/api/method/my_app.api.ping_server \
  -H "Authorization: token api_key:api_secret" \
  -d "message=Hello Frappe"

Conclusion

Frappe's REST API is incredibly powerful and saves developers hundreds of hours of boilerplate code. Combined with RPC methods, you can build practically any integration seamlessly.