Handling 412 Precondition Failed and 428 Precondit...

ryutaro_umezuki1 · ‎04-03-2023

Background

There are many excellent blogs available that provide an overview of ETag and its usage in tutorials. In this blog post, the focus is on how to handle common 'errors' that occur when using SAP APIs that use ETag or If-Match. This post begins by explaining the roles of ETag and If-Match in SAP APIs.

ETag and If-Match in the SAP API context

The ETag system is a unique identifier that represents the state of a resource at a particular point in time. In SAP APIs, Etags are generated for each resource and can be used to ensure that you are working with the latest up-to-date version of the resource. The format is like W'''0001''' or W/"SADL-020230301000000C~20230318000000". When you make a request to a SAP API that includes a If-Match key and an Etag value, the server checks the value against the current state of the resource. If the Etag value does not match the current state, the API returns an error message and requires the requester to retrieve the updated Etag value. ETag provides mainly two benefits:

It reduces excessive network communication between the client and server by serving as a cache key in the HTTP GET method.

It prevents unintended updates and ensures safety outside of the GET method.

The second benefit is the focus of this blog post.

Scenario

To understand the role of ETag, let's consider a scenario in a warehouse where a picker is tasked with retrieving an item from the inventory. The picker scans the item and updates the inventory using an SAP API that incorporates an ETag system. SAP S/4HANA generates a unique ETag value for the item's inventory record when the picker scans the item. The client then retrieves and stores the ETag value for future reference.

Picker scans the barcode of an item

However, while the first picker is processing the inventory update, if another picker tries to scan the same item, the API checks the Etag value against the current state of the item's inventory record and requests the second picker to retrieve the updated Etag value before performing the update. It prevents the risk of unintended updates to the inventory, which can lead to errors and delays.

HTTP requests in order of time

* To make it easy to understand visually, the format W/"YYYYMMDDHHMMSS'' is be used to represent dates and times in chronological order.

Implementation steps

Now that you have a good understanding of the concept and its use case, let's take a look at how to use it with APIs by using SAP warehouse APIs. To make a request, you need to use the SAP API Business Hub, which can be found at the following URL:

https://api.sap.com/api/WAREHOUSEORDER_0001/resource

When the picker scans the item, the POST method below including an If-Match key in the Header is used.

https://<host>-api.s4hana.ondemand.com/sap/opu/odata4/sap/api_warehouse_order_task_2/srvd_a2x/sap/warehouseorder/0001/WarehouseTask(EWMWarehouse='1050',WarehouseTask='1000000000',WarehouseTaskItem='0')/SAP__self.ConfirmWarehouseTaskProduct

These two steps need to be performed in terms of the ETag.

Step1 - Call the GET method API

Use the following URL:

https://<host>-api.s4hana.ondemand.com/sap/opu/odata4/sap/api_warehouse_order_task_2/srvd_a2x/sap/warehouseorder/0001/WarehouseTask(EWMWarehouse='1050',WarehouseTask='1000001114',WarehouseTaskItem='0')

GET method on Postman

Step2 - Call the POST method API

You should use the same URL path and parameters as the GET method, with the addition of the ETag value of the If-Match key in the request. However, it includes '/SAP__self.ConfirmWarehouseTaskProduct', which is different from the GET method. Some APIs may use subdirectories, such as '/SAP__self.ConfirmWarehouseTaskProduct' in this case, so please refer to the official SAP documentation for specifications to ensure accuracy. Additionally, please note that you can verify that the API with the path ending in /SAP__self.ConfirmWarehouseTaskProduct points to the same record as the GET method.

Here is the URL:

https://<host>-api.s4hana.ondemand.com/sap/opu/odata4/sap/api_warehouse_order_task_2/srvd_a2x/sap/warehouseorder/0001/WarehouseTask(EWMWarehouse='1750',WarehouseTask='1000001114',WarehouseTaskItem='0')/SAP__self.ConfirmWarehouseTaskProduct

POST method on Postman

When you call the POST method on Postman, you should receive a 204 status code if everything goes smoothly.

Success response on Postman

However, during the development phase, you may encounter some errors related to the ETag.

428 Precondition Required

This error occurs when you don't provide a precondition header such as "If-Match" or "If-None-Match". You can rectify it by taking one of two approaches:

1. Set If-Match to * (Not recommended)

This asterisk is a special value that represents any resources. If there are any values on SAP S/4HANA, this value will be treated as the latest value, even if the resource has been modified by another request in the meantime. In short, this approach can lead to conflicts and unintended updates, and it undermines the ETag function itself. You should avoid using it unless you have a specific reason to do so.

2. Set If-Match to <current-etag-value> (Recommended)

As mentioned above, this approach involves requesting the GET method first and then requesting the POST method, including the ETag value to If-Match key obtained from the first method. This approach is recommended over using the asterisk.

412 Precondition Failed

This error indicates that the server does not meet one of the preconditions that the requester put on the request header fields. The error could be due to the following:

1. Use not the latest ETag

If the ETag is not up-to-date, a 412 error is generated. The solution is to retrieve the ETag for that record again using the HTTP GET method.

2. Use the ETag of different URL

This is a common mistake that can be tricky to troubleshoot. The GET method used to retrieve an ETag must be from the same record(s) as the POST, PUT, or DELETE methods used to modify the record(s). This means that if you are referencing different records or referencing a parent table's record, the 428 error can occur.

In the SAP warehouse API example for picking in a warehouse, there is a table called "Warehouse order" with columns like EWMWarehouse and WarehouseOrderStatus. Additionally, there is a child table list called "_WarehouseTask" that stores information about the items to be picked.

To create an application for the picking process, one might think of the following steps:

Request a GET method to obtain the order data and the list of tasks, and the response includes an ETag. (The path: /WarehouseOrder(EWMWarehouse='{EWMWarehouse}',WarehouseOrder='{WarehouseOrder}'))

Display the order data and the list of tasks on one screen.

Request a POST method to inform that the item is picked. (the path: /WarehouseTask(EWMWarehouse='{EWMWarehouse}',WarehouseTask='{WarehouseTask}',WarehouseTaskItem='{WarehouseTaskItem}')./SAP__self.ConfirmWarehouseTaskProduct), If-Match: <The ETag of first step>

However, this approach will result in a 412 error. The correct way to do this is:

Request a GET method to obtain the order data and the list of tasks, and the response includes an ETag. (The path: /WarehouseOrder(EWMWarehouse='{EWMWarehouse}',WarehouseOrder='{WarehouseOrder}'))

Display the order data and the list of tasks on one screen.

Request a GET method to obtain the ETag value. (The path: /WarehouseTask(EWMWarehouse='{EWMWarehouse}',WarehouseTask='{WarehouseTask}',WarehouseTaskItem='{WarehouseTaskItem}'))

Request a POST method to inform that the item is picked. (the path: /WarehouseTask(EWMWarehouse='{EWMWarehouse}',WarehouseTask='{WarehouseTask}',WarehouseTaskItem='{WarehouseTaskItem}')./SAP__self.ConfirmWarehouseTaskProduct), If-Match: <The ETag of third step>

Wrong table ETag

Another example involves an online store where you use a GET API to retrieve a list of products, including their ETag information. If you then try to buy one of these products using the PUT method and use the ETag from the GET request, a 428 error can occur. To fix this, make sure to use the proper URL GET request before making any modifications.

Online store

Conclusion

In conclusion, this blog post has discussed common mistakes when using SAP APIs that involve ETag or If-Match and how to fix them. Correctly using the ETag system is crucial to safeguard data safety and integrity and prevent errors and delays. By following the steps provided in this post and correcting errors appropriately, you can make the most of the ETag system's benefits and ensure your SAP APIs run smoothly.

If you notice any mistakes in this blog post or have any feedback, please let me know.

References

ETag

If-Match