Upserts and Conditional Creation

When a supplier reports a product's stock level, the bookstore may or may not already have a record for it. The first report needs to create a resource; later reports need to replace its quantity. A different integration may have permission only to initialize a stock level and must never overwrite an existing one.

Those are different intentions.

This chapter explains upserts, identity matching, create-only conditions, concurrent requests, permissions, and retry outcomes. The examples use a fictional bookstore JSON API over HTTPS at https://api.bookstore.example.