Adds readme doc for share API usage

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Author: DarshitChanpura

README.md

@@ -22,6 +22,7 @@ OpenSearch Security is a plugin for OpenSearch that offers encryption, authentic
   - [Installation](#installation)
   - [Test and Build](#test-and-build)
   - [Config hot reloading](#config-hot-reloading)
+  - [Resource Sharing API](#resource-sharing-api)
   - [Onboarding new APIs](#onboarding-new-apis)
     - [System Index Protection](#system-index-protection)
   - [Contributing](#contributing)
@@ -113,6 +114,149 @@ The Security Plugin configuration is stored in a dedicated index in OpenSearch i
 * Configuration changes do not require a restart
 * Configuration changes take effect immediately
 
+## Resource Sharing API
+
+The Security Plugin, starting v3.2.0, introduces a share API that can be used by opensearch-dashboards and/or REST client to enable resource-owners to share their resources. A resource is currently defined as a document in an index. The feature grants creators of the document access to share it with other entities, i.e., users, roles or backend_roles.
+The feature is proposed in this GitHub issue: https://github.com/opensearch-project/security/issues/4500
+
+The API supports 3 HTTP methods:
+
+### 1. `PUT /_plugins/_security/api/resource/share`
+
+**Description:**
+Share a resource with users, roles, or backend roles at specific access levels.
+This **replaces** any existing sharing configuration.
+
+**Request Body:**
+
+```json
+{
+  "resource_id": "resource-123",
+  "resource_index": "my-resource-index",
+  "share_with": {
+    "read_only": {
+      "users": ["alice"],
+      "roles": ["readers"],
+      "backend_roles": ["data-readers"]
+    },
+    "read_write": {
+      "users": ["bob"]
+    }
+  }
+}
+```
+
+**Success Response:**
+
+```json
+{
+  "sharing_info": {
+    "resource_id": "resource-123",
+    "created_by": { "username": "admin" },
+    "share_with": {
+      "read_only": {
+        "users": ["alice"],
+        "roles": ["readers"],
+        "backend_roles": ["data-readers"]
+      },
+      "read_write": {
+        "users": ["bob"]
+      }
+    }
+  }
+}
+```
+
+### 2. `PATCH /_plugins/_security/api/resource/share`
+
+**Description:**
+**Adds** and/or **removes** recipients from access levels.
+Does **not** overwrite the entire sharing configuration.
+
+**Request Body:**
+
+```json
+{
+  "resource_id": "resource-123",
+  "resource_index": "my-resource-index",
+  "patch": {
+    "share_with": {
+      "read_only": {
+        "users": ["charlie"]
+      }
+    },
+    "revoke": {
+      "read_only": {
+        "users": ["alice"]
+      },
+      "read_write": {
+        "users": ["bob"]
+      }
+    }
+  }
+}
+```
+
+**Success Response:**
+
+```json
+{
+  "sharing_info": {
+    "resource_id": "resource-123",
+    "created_by": { "username": "admin" },
+    "share_with": {
+      "read_only": {
+        "users": ["charlie"],
+        "roles": ["readers"],
+        "backend_roles": ["data-readers"]
+      },
+      "read_write": {}
+    }
+  }
+}
+```
+
+**Allowed Patch Keys:**
+
+* `"share_with"`
+* `"revoke"`
+
+
+### 3. `GET /_plugins/_security/api/resource/share?resource_id=<id>&resource_index=<index>`
+
+**Description:**
+Returns the current sharing configuration for a resource.
+
+**Query Parameters:**
+
+* `resource_id` (required)
+* `resource_index` (required)
+
+**Example Request:**
+
+```
+GET /_plugins/_security/api/resource/share?resource_id=resource-123&resource_index=my-resource-index
+```
+
+**Success Response:**
+
+```json
+{
+  "sharing_info": {
+    "resource_id": "resource-123",
+    "created_by": { "username": "admin" },
+    "share_with": {
+      "read_only": {
+        "users": ["charlie"],
+        "roles": ["readers"],
+        "backend_roles": ["data-readers"]
+      },
+      "read_write": {}
+    }
+  }
+}
+```
+
 ## Onboarding new APIs
 
 It is common practice to create new transport actions to perform different tasks between nodes when developing new APIs. For any new or existing plugins that want to onboard & integrate these actions with security, they should follow the steps below: