Add Duplicate Writes documentation (#1105)

Author: tylernix

docs/README.md

@@ -72,7 +72,6 @@ It offers an HTTP API, a gRPC API, and has SDKs for programming languages includ
   - [Manage Group Access](./content/interacting/managing-user-access.mdx)
   - [Manage Group Membership](./content/interacting/managing-group-membership.mdx)
   - [Manage Relationships Between Objects](./content/interacting/managing-relationships-between-objects.mdx)
-  - [Transactional Writes](./content/interacting/transactional-writes.mdx)
   - [Relationship Queries](./content/interacting/relationship-queries.mdx)
   - [Get Tuple Changes](./content/interacting/read-tuple-changes.mdx)
   - [Search with Permissions](./content/interacting/search-with-permissions.mdx)

docs/content/getting-started/perform-check.mdx

@@ -144,11 +144,11 @@ To obtain the [access token](https://auth0.com/docs/get-started/authentication-a
 
 ### 02. Calling Check API
 
-To check whether user `user:anne` has relationship `can_view` with object `document:Z`
+To check whether user `user:anne` has relationship `reader` with object `document:Z`
 
 <CheckRequestViewer
   user={'user:anne'}
-  relation={'can_view'}
+  relation={'reader'}
   object={'document:Z'}
   allowed={true}
   skipSetup={true}

docs/content/getting-started/update-tuples.mdx

@@ -2,7 +2,7 @@
 title: Update Relationship Tuples
 sidebar_position: 3
 slug: /getting-started/update-tuples
-description: Updating system state by writing and deleting relationship tuples
+description: Introduction to adding and deleting relationship tuples
 ---
 
 import {
@@ -24,7 +24,7 @@ import TabItem from '@theme/TabItem';
 
 <DocumentationNotice />
 
-This section will illustrate how to update _<ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuples" />_.
+This is an introduction to adding and deleting _<ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuples" />_.
 
 ## Before you start
 
@@ -93,7 +93,7 @@ Assume that you want to add user `user:anne` to have relationship `reader` with
 {
   user: 'user:anne',
   relation: 'reader',
-  object: 'document:Z',
+  object: 'document:Z'
 }
 ```
 
@@ -150,7 +150,7 @@ To add the relationship tuples, we can invoke the write API.
     {
       user: 'user:anne',
       relation: 'reader',
-      object: 'document:Z',
+      object: 'document:Z'
     },
   ]}
   skipSetup={true}
@@ -175,7 +175,7 @@ Assume that you want to delete user `user:anne`'s `reader` relationship with obj
 {
   user: 'user:anne',
   relation: 'reader',
-  object: 'document:Z',
+  object: 'document:Z'
 }
 ```
 
@@ -184,7 +184,7 @@ Assume that you want to delete user `user:anne`'s `reader` relationship with obj
     {
       user: 'user:anne',
       relation: 'reader',
-      object: 'document:Z',
+      object: 'document:Z'
     },
   ]}
   skipSetup={true}
@@ -199,11 +199,113 @@ Assume that you want to delete user `user:anne`'s `reader` relationship with obj
   ]}
 />
 
+### 04. Writing and deleting relationship tuples in the same request
+
+You can combine both writes and deletes in a single transactional API request. This is useful when you need to update multiple relationships atomically. All operations in the request will either succeed together or fail together.
+
+The Write API allows you to send up to `100` unique tuples in the request. (This limit applies to the sum of both writes and deletes in that request).
+
+For example, you might want to remove `user:anne` as a `writer` of `document:Z` while simultaneously updating `user:anne` as an `reader` of `document:Z`:
+
+<WriteRequestViewer
+  relationshipTuples={[
+    {
+      user: 'user:anne',
+      relation: 'reader',
+      object: 'document:Z'
+    },
+  ]}
+  deleteRelationshipTuples={[
+    {
+      user: 'user:anne',
+      relation: 'writer',
+      object: 'document:Z'
+    },
+  ]}
+  skipSetup={true}
+  allowedLanguages={[
+    SupportedLanguage.JS_SDK,
+    SupportedLanguage.GO_SDK,
+    SupportedLanguage.DOTNET_SDK,
+    SupportedLanguage.PYTHON_SDK,
+    SupportedLanguage.JAVA_SDK,
+    SupportedLanguage.CLI,
+    SupportedLanguage.CURL,
+  ]}
+/>
+
+This approach ensures that both operations succeed or fail together, maintaining transactional data consistency.
+
+
+:::note
+When using the Write API, you cannot include the same tuple (same user, relation, and object) in the writes or deletes arrays within a single request. The API will return an error with code `cannot_allow_duplicate_tuples_in_one_request` if detected.
+:::
+
+### 05. Ignoring duplicate or missing tuples
+
+Sometimes you might need to write a tuple that already exists, which would normally cause the whole request to fail. You can use the `on_duplicate: "ignore"` parameter to handle this gracefully. 
+
+This is particularly useful for high-volume data imports, migrations, or ensuring certain permissions exist without complex error handling logic.
+
+For example, if you want to ensure `user:anne` has `reader` access to `document:Z` without worrying about whether the relationship already exists in <ProductName format={ProductNameFormat.ShortForm}/>:
+
+<WriteRequestViewer
+  relationshipTuples={[
+    {
+      user: 'user:anne',
+      relation: 'reader',
+      object: 'document:Z'
+    },
+  ]}
+  writeOptions={{
+    on_duplicate: 'ignore',
+  }}
+  skipSetup={true}
+  allowedLanguages={[
+    SupportedLanguage.CURL,
+  ]}
+/>
+
+:::caution
+At the moment, this feature is only available on the API (v1.10.0). Supported SDKs will follow shortly after.
+:::
+
+Similarly, you can use `on_missing: "ignore"` when deleting tuples that might not exist.
+
+<WriteRequestViewer
+  skipSetup={true}
+  deleteRelationshipTuples={[
+    {
+      user: 'user:anne',
+      relation: 'writer',
+      object: 'document:Z'
+    },
+  ]}
+  deleteOptions={{
+    on_missing: 'ignore',
+  }}
+  expectedResponse={{
+    data: {},
+  }}
+  allowedLanguages={[
+    SupportedLanguage.CURL,
+  ]}
+/>
+
+The behavior of `on_duplicate: "ignore"` is more nuanced for tuples with conditions.
+- **Identical Tuples**: If a tuple in the request is identical to an existing tuple (same user, relation, object, condition name, and condition context), it will be safely ignored.
+- **Conflicting Tuples**: If a tuple key (user, relation, object) matches an existing tuple, but the condition name or parameters are different, this is a conflict. The write attempt will be rejected, and the entire transaction will fail with a `409 Conflict` error.
+
 ## Related Sections
 
 <RelatedSection
   description="Check the following sections for more on how to write your authorization data"
   relatedLinks={[
+     {
+      title: 'Write API',
+      description: 'Learn more about the Write API options.',
+      link: '/api/service#Relationship%20Tuples/Write',
+    },
     {
       title: 'Managing User Access',
       description: 'Learn about how to give a user access to a particular object.',
@@ -216,11 +318,5 @@ Assume that you want to delete user `user:anne`'s `reader` relationship with obj
       link: '../interacting/managing-group-access',
       id: '../interacting/managing-group-access.mdx',
     },
-    {
-      title: 'Transactional Writes',
-      description: 'Learn about how to update multiple relations within the same API call.',
-      link: '../interacting/transactional-writes',
-      id: '../interacting/transactional-writes.mdx',
-    },
   ]}
 />

docs/content/interacting/overview.mdx

@@ -42,11 +42,6 @@ This section helps you integrate <ProductName format={ProductNameFormat.ShortFor
         'Write relationship tuples to manage how two objects are related. E.g. parent folder and child document.',
       to: 'interacting/managing-relationships-between-objects',
     },
-    {
-      title: 'Transactional Writes',
-      description: 'Write multiple relationship tuples in a single request, so all writes either succeed or fail.',
-      to: 'interacting/transactional-writes',
-    },
     {
       title: 'Relationship Queries',
       description: 'An overview of how to use the Check, Read, Expand, and ListObject APIs.',