Prevent Duplicate Resource Creation in HTTP APIs with a POST‑then‑PUT Pattern

In recent years I have worked with many HTTP APIs that are often private and suffer from design flaws that affect reliability and integrability.

A common problem is the accidental creation of duplicate resources, especially when resource creation is tied to critical operations such as payments.

For example, PayPal’s Create Payment API creates a payment as soon as a POST request to /v1/payments/payment is made. If the network fails, the client may not receive the payment ID and cannot determine whether the charge succeeded, and automatic retries can cause double charging.

PayPal suggests using a PayPal‑Request‑Id header or an invoice number to deduplicate requests, but these solutions are cumbersome for users.

Using POST/PUT to avoid duplicate resource creation

By designing the API so that POST only creates a database record and returns an identifier, while the actual resource creation is performed with a subsequent PUT (or PATCH), duplicate creation can be avoided. The diagram illustrates this flow.

With this approach, if a network error occurs, retrying a POST only creates an empty placeholder, while retrying a PUT is safe because PUT is idempotent.

The POST/PUT pattern may require two requests to fully create a resource, but it scales well for high‑volume scenarios and leads to more stable, reliable APIs.

Thank you for reading; I hope this helps.