A Step-by-Step Guide to Frappe REST API Permissions and Data Filtering

The default API URL to access data is structured as:

[appURL]:[PortNumber]/api/v2/document/[docTypeName]

Let’s construct a URL based on this rule:

http://trysite:8000/api/v2/document/Driver

By default, this will return a 403 Forbidden error, indicating a permissions issue.

Attaining the Required Permissions

To gain access, follow these steps:

1. Navigate to User > [userName].
2. Scroll down and locate the API Access section.
3. Generate an API Secret. Note that the API Secret will only be generated once, so keep it safe.

You will need both the API Key and API Secret to make a successful request.

Authorization: token [APIkey]:[APIsecret]

Filtering Data from the API

Filtering Specific Fields

To filter specific fields from the response, the structure of the URL is as follows:

APIEndpoint?fields=["field_name"]

Example:

http://batsite:8000/api/v2/document/Driver?fields=["first_name","last_name"]

Filtering All Fields

To retrieve all fields from a document, use the wildcard * in the fields parameter:

http://batsite:8000/api/v2/document/Driver?fields=["*"]

Fetching a Single Entry

To fetch a specific document by its unique ID, construct the endpoint as follows:

APIEndpoint/document/[docTypeName]/[SingleDocID]

Example:

http://batsite:8000/api/v2/document/Driver/DR-0001

API Endpoint (POST Request)

To create a new document, construct the endpoint using the docType and pass the required data in JSON format.

http://batsite:8000/api/v2/document/Driver

Pass the body parameters as JSON:

{
  "first_name": "Rafique",
  "last_name": "Ullah",
  "license_number": "TDR3445"
}