REST API

Frappe framework generates REST API for all of your DocTypes out of the box. You can also run arbitrary python methods using their dotted module path.

Authentication

There are two ways to authenticate through Frappe REST API. Token based authentication and password based authentication.

1. Token Based Authentication

A token is a pair of API Key and API Secret. First, you must create an API User and then generate the keys in the API Access section in the User form.

The token is generated by concatenating api_key and api_secret with a colon :. Pass the string token api_key:api_secret to the Authorization header in the request.

fetch('http://<base-url>/api/method/frappe.auth.get_logged_user', {
    headers: {
        'Authorization': 'token api_key:api_secret'
    }
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

2. Password Based Authentication

Password based authentication relies on cookies and session data to maintain authentication in subsequent requests. In most cases, the library you are using to issue REST calls will handle session data, but if it doesn't you should use Token based authentication.

fetch('http://<base-url>/api/method/login', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        usr: 'username or email',
        pwd: 'password'
    })
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

Listing Documents

To get a list of records of a DocType, send a GET request at /api/resource/:doctype. By default, it will return 20 records and will only fetch the name of the records.

GET /api/resource/:doctype

Response

{
  "data": [
    {
      "name": "b57566801d"
    },
    {
      "name": "b63b71df37"
    },
    {
      "name": "1fea4af0f4"
    },
    {
      "name": "4ca0cc6e0e"
    },
  ]
}

You can specify which fields to fetch in the fields param. It should be a JSON array.

GET /api/resource/:doctype?fields=["field1", "field2"]

You can filter the records by passing filters param. Filters should be an array, where each filter is of the format: [field, operator, value]

GET /api/resource/:doctype?filters=[["field1", "=", "value1"], ["field2", ">", "value2"]]

You can also provide the sort field and order. It should be of the format fieldname asc or fieldname desc. The space should be URL encoded.

GET /api/resource/:doctype?order_by=title%20desc

You can also page the results by providing the limit_start and limit_page_length params.

GET /api/resource/:doctype?limit_start=10&limit_page_length=20

CRUD Operations

Frappe generates REST endpoints for CRUD operations for all DocTypes automatically. Make sure you set the following headers in your requests so that you get proper JSON responses.

{
    "Accept": "application/json",
    "Content-Type": "application/json",
}

Create

Create a new document by sending a POST request to /api/resource/:doctype. Send the document as JSON in the Request Body.

POST /api/resource/:doctype

# Body
{"description": "New ToDo"}

Response

{
  "data": {
    "name": "af2e2d0e33",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "New ToDo",
    "doctype": "ToDo"
  }
}

Read

Get a document by sending a GET request to /api/resource/:doctype/:name.

GET /api/resource/:doctype/:name

Response

{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "<p>Test description</p>",
    "doctype": "ToDo"
  }
}

Update

Update a document by sending a PUT request to /api/resource/:doctype/:name. You don't need to send the whole document, instead you can just send the fields that you want to update.

PUT /api/resource/:doctype/:name

# Body
{"description": "New description"}

Response

{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:21:00.785117",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "New description",
    "doctype": "ToDo"
  }
}

Delete

Delete a document by sending a DELETE request to /api/resource/:doctype/:name.

DELETE /api/resource/:doctype/:name

Response

{"message": "ok"}

Remote Method Calls

Frappe allows you to trigger arbitrary python methods using the REST API for handling custom logic. These methods must be marked as whitelisted to make them accessible via REST.

To run a whitelisted python method at frappe.auth.get_logged_user, send a request to the endpoint /api/method/frappe.auth.get_logged_user.

GET /api/method/frappe.auth.get_logged_user

Response

{
  "message": "john@doe.com"
}
  • If your method returns some values, you should send a GET request.
  • If your method changes the state of the database, use POST. After a successful POST request, the framework will automatically call frappe.db.commit() to commit the changes to the database.
  • A successful response will return a JSON object with a message key.
  • An errored response will return a JSON object with exc key which contains the stack trace and exc_type which contains the thrown Exception.
  • The return value of the method will be converted to a JSON and sent as the response.

File Uploads

There is a dedicated method /api/method/upload_file that accepts binary file data and uploads it into the system.

Here is the curl command for it:

curl -X POST \
  http://<base-url>/api/method/upload_file \
  -H 'Accept: application/json' \
  -H 'Authorization: token xxxx:yyyy' \
  -F file=@/path/to/file/file.png

If you are using client side Javascript to upload files, you can append the uploaded files as FormData and send an XHR request. Here is the implementation code in Frappe Desk.