Introduction
In this guide, we are going to delve into the details of one of Empress’s key features - Listing Documents. This backend feature plays a significant role in building and customizing business solutions. It provides developers with an efficient way to retrieve specific data from your Empress server using a GET request to the /api/resource/{doctype} endpoint.
1. Basic GET Request
To list documents, you send a basic GET request to the endpoint, replacing {doctype} with the name of the document type you want to access.
/api/resource/Person
The response from this request is a JSON object, with the key data containing an array of document listings.
2. Pagination
By default, the response is paginated to present 20 items at a time. However, you have control over this setting and can modify it by passing the limit_page_length query parameter. To request successive pages, pass limit_start.
3. Customizing Field Retrieval
Only the name field is included in the default listing. However, Empress gives you the option to add more fields to your listing. You can do this by passing the fields parameter with your GET request.
This parameter should be a JSON array containing the fieldnames you want to add.
/api/resource/Person/?fields=["name","first_name"]
This will return a response that includes both the name and first_name fields in the document listing.
4. Filtering Listings
To filter the listings you retrieve, Empress allows you to apply SQL conditions using the filters query parameter. This parameter should be a JSON array containing one or multiple filters. Each filter is an array in the format [{doctype}, {field}, {operator}, {operand}].
For example, to get the name (id) of all persons with the first name “Jane”, you would send:
/api/resource/Person?filters=[["Person","first_name","=","Jane"]]
This will return a response that only includes listings where the first_name field is equal to “Jane”.
Conclusion
The Listing Documents feature is a powerful tool in the arsenal of any developer working with Empress. It allows you to efficiently retrieve, customize, and filter document listings, providing a flexible way to access and manipulate data. Mastering this feature is key to developing and customizing sophisticated business solutions with Empress.