By default, Edge Security Accelerator (ESA) nodes treat POST requests as dynamic requests. The requests bypass the cache module and are forwarded directly to the origin server. ESA nodes do not cache the responses from the origin server. After you enable POST caching, ESA nodes can cache the responses to POST requests and serve the cached content to subsequent identical requests.
Use cases
POST caching is ideal for scenarios that involve reusable query results. A typical example is:
Product information queries on an e-commerce site (search-like API)
-
Scenario description: The frontend sends a POST request with a JSON object containing query conditions, such as filtering, pagination, and aggregation. The backend returns structured data.
-
Why use POST: Complex query parameters can exceed URL length limits, making them unsuitable for GET requests.
-
Value of caching: Caching the results of popular queries, such as
Product type: Footwear; Style: Running shoes; Gender: Men's; Price range: 300–600;, reduces the load on your database.
How it works
After you enable the POST caching feature, an ESA POP that receives a POST request from a client converts the request to a GET request and then processes it by following the caching procedure for static resources. If the resource is not cached on the ESA POP or the cached resource has expired, the ESA POP reverts the request to a POST request and then forwards it to the origin server.
Notes
-
Cache time-to-live (TTL): POST caching is often used for information queries. We recommend setting a short cache time-to-live (TTL), from a few seconds to a few minutes.
-
Cache purge mechanism: When you update data on your origin server, you must actively purge the relevant cached content to prevent clients from receiving stale data.
-
Security: To prevent data leaks, do not cache POST responses that contain sensitive user data, such as personal billing information.
Procedure
-
In the ESA console, choose Websites. In the Website column, click the target site.
-
In the left-side navigation pane, choose .
-
Click Create Rule and enter a Rule Name.
-
In the If requests match... section, define the matching conditions for your requests. For more information, see Rule expression syntax.
-
In the Cache POST section, click Configure, set the POST caching parameters, and then click OK:
-
Status: Enables or disables the POST caching feature.
-
Body Size: The maximum size of the body in a POST request from a client. The value must be between 1 KB and 8 KB. If the body of a request exceeds this limit, the ESA node forwards the request to the origin server as a dynamic request and does not use the caching workflow to process it.
-
CacheKey Processing: Determines the cache key that an ESA node uses when it caches responses from an origin server. We recommend that you include the MD5 hash value of the request body in the cache key. Otherwise, requests with different bodies may hit the same cache. The following two processing modes are supported:
-
Generate MD5 hash of request body and store it in CacheKey
-
Ignore Request Body
-
-
Configuration examples
The following examples show recommended POST caching settings for common use cases.
Example 1: Product search and filter API
Scenario: An e-commerce frontend sends a POST request with a JSON object that contains filter conditions, such as category, price range, and sort order. While many queries are unique, popular search combinations are frequently reused. To avoid returning incorrect results, each distinct query requires a separate cache entry.
Recommended configuration
|
Parameter |
Recommended setting |
|
POST caching |
Enabled |
|
Body Size Limit |
4 KB. Since a typical JSON search request is 1–3 KB, this setting provides an adequate buffer. |
|
Cache Key Handling Mode |
Generate MD5 hash of request body and store it in CacheKey. This method generates a unique cache key for each set of query conditions, ensuring that each query is cached independently. |
Result: Requests with identical filter conditions hit the cache, reducing database queries. Caching different filter combinations independently prevents interference.
Example 2: Site-wide public data query
Scenario: An admin backend uses a POST request to fetch site-wide real-time statistics, such as daily order totals or the number of online users. Because all users accessing this endpoint should receive the same data, requests can share a single cache entry. The cache should therefore ignore the request body, which might contain client-specific identifiers.
Recommended configuration
|
Parameter |
Recommended setting |
|
POST caching |
Enabled |
|
Body Size Limit |
2 KB. The request body is small and contains only a few identifiers. |
|
Cache Key Handling Mode |
Ignore Request Body. All POST requests share the same cache entry. Differences in the request body do not affect cache hits. |
Result: After the first request is served from the origin, all subsequent requests hit the same cache entry. This significantly reduces concurrent load on the origin server.
FAQ
Adjusting the body size limit
The body size limit determines which POST requests are eligible for caching. Requests that exceed this limit are forwarded directly to the origin server without being cached. Consider the following when setting the limit:
-
Increase the limit (for example, to 6 KB–8 KB): If your POST requests have complex or large request bodies, such as search queries with nested structures or aggregation queries with multi-dimensional filter parameters, a higher limit is necessary. This ensures these requests are cached, maximizing performance benefits.
-
Use a smaller limit (for example, 1 KB–2 KB): If your POST requests contain only simple parameters or a few identifiers, such as a user ID or a timestamp, a large limit is unnecessary.