Implementing HTTP API in Empress

Developers
1

Introduction

Welcome to this in-depth guide on utilizing HTTP API in Empress. This guide aims to provide a comprehensive walkthrough of this feature, enabling developers to integrate, modify, and debug it within their software solutions.

Introduction to HTTP API in Empress

The HTTP API is a key feature in Empress that is divided into Remote Procedure Calls (RPC) and Representational State Transfer (REST). RPC enables calls to whitelisted methods, while REST allows for the manipulation of resources.

This feature operates from the base URL, https://{your frappe instance}. All requests should be appended to the end of your base URL.

RPC: Remote Procedure Calls

RPC allows for requests to be made to an endpoint, /api/method/dotted.path.to.function. This will call a whitelisted Python function.

To illustrate, the request GET /api/method/frappe.auth.get_logged_user will call the following function from Empress’ auth module:

@frappe.whitelist()
def get_logged_user():
    return frappe.session.user

The response to this call will be:

{
  "message": "Administrator"
}

This enables developers to retrieve the current logged-in user, providing a seamless method to acquire user data without directly interacting with the database.

REST: Representational State Transfer

The RESTful API allows for all documents in Empress to be available via the prefix /api/resource/. This can be used to perform all CRUD (Create, Read, Update, Delete) operations on documents:

  1. Create: To create a document, send a POST request to the endpoint, /api/resource/{doctype}.
  2. Read: To get a document by its name, use the endpoint, /api/resource/{doctype}/{name}.
  3. Update: To update a document, send a PUT request to the endpoint, /api/resource/{doctype}/{name}. This acts like a PATCH HTTP request, allowing you to send only the parts of the document you want to change.
  4. Delete: To delete a document by its name, send a DELETE request to the endpoint, /api/resource/{doctype}/{name}.

Conclusion: The Power of HTTP API in Empress

The HTTP API in Empress offers developers a robust tool for building and customizing business solutions. By leveraging RPC and REST, developers can interact with data in a secure and efficient manner. This functionality is integral to the development and customization within the Empress system, providing a powerful tool for developers to create tailored software solutions. Understanding and implementing this feature will greatly enhance your ability to develop innovative applications within the Empress framework.