Understanding Empress Framework REST API

Developers
1

Introduction

Welcome, developers. In this guide, we’ll delve into the Empress Framework REST API, a vital feature in Empress. With this feature, Empress generates REST APIs for all your DocTypes automatically. In addition, you can run arbitrary python methods using their dotted module path.

Authentication

Two methods for authentication exist: token-based and password-based.

1. Token-Based Authentication

Token-based authentication involves generating a pair of API Key and API Secret. Follow these steps:

# Step 1: Go to User list and open a user.
# Step 2: Click on the "Settings" tab. (Skip if you don't see tabs)
# Step 3: Expand the API Access section and click on Generate Keys.
# Step 4: Copy the API Secret from the popup and keep it safe.
# Step 5: You will also see another field "API Key" in this section.

The token is generated by concatenating api_key and api_secret with a colon :. Pass this concatenated string 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);
})

➜ curl http://<base-url>/api/method/frappe.auth.get_logged_user -H "Authorization: token api_key:api_secret"

2. Password-Based Authentication

Password-based authentication relies on cookies and session data. In most cases, the library you are using to issue REST calls will handle session data.

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);
})

➜ curl --cookie-jar snowcookie --request POST "http://<base-url>/api/method/login" -H 'Content-Type: application/json' -H 'Accept: application/json' --data-raw "{ \"usr\" : \"<username>\", \"pwd\": \"<password>\" }"
{"message":"Logged In","home_page":"/app","full_name":"<user:full_name>","dashboard_route":"/sites"}

➜ curl --cookie snowcookie --request POST "http://<base-url>/api/method/frappe.auth.get_logged_user" -H 'Accept: application/json'
{"message":"<username>"}

CRUD Operations

Empress generates REST endpoints for CRUD operations for all DocTypes automatically. Make sure you set the following headers in your requests to 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"}

Read

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

GET /api/resource/:doctype/:name

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"}

Delete

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

DELETE /api/resource/:doctype/:name

Summary

Empress Framework’s REST API is an essential feature in Empress that allows for seamless integration and customization of business solutions. It provides robust mechanisms for authenticating users and maintaining secure connections, as well as performing CRUD operations and calling arbitrary Python methods. Moreover, it offers capabilities for listing documents and uploading files, enabling developers to build rich, data-driven applications. By understanding and leveraging the Empress Framework’s REST API, developers can create sophisticated applications that can easily be customized and scaled to meet business needs.