> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/fabric-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/fabric-knowledge-base/api/api-documentation/user-service/partial-update-endpoint-for-policies.md).

# Partial update endpoint for policies

Related ticket: FABRIC-8035

This document explains the background, problem, and solution related to updating user policy permissions in **UserService**.

### 🧠 Background

Until now, clients used the `PUT /policies/:id` endpoint to update a policy’s permissions.\
Each policy has a `permissions` object, which can be large and include many nested items such as catalog permissions.

Previously, even if you wanted to change just **one small part** (for example, update a single flag under `userGroups`), the system required you to send the **entire permissions payload** again.

***

### ❌ What Was the Problem?

Our review showed that the `PUT` endpoint was **replacing** the entire permissions object instead of updating just the part that changed.\
This meant the client had to always send the full permissions structure — often a large JSON file — even for tiny updates.

As a result:

* Requests became unnecessarily large.
* Processing took longer.
* Some requests even timed out when handling very big policies.

**Example:**\
If a client had over 1,000 catalogs attached to a policy, changing one permission still required sending the entire permissions payload.

***

### ✅ What’s New

We’ve introduced a new, optimized endpoint that supports **partial updates** —\
so you can now send **only what has changed** instead of the whole permissions object.

#### Key benefits:

* Faster requests and responses.
* Smaller payloads.
* No need to resend existing permissions.
* All other permissions remain untouched.

***

### 🧩 New Endpoint

**`PATCH /api/policies/{id}`**

**Description:**\
Partially updates a policy’s permissions.

**Headers:**

| Header         | Description                      |
| -------------- | -------------------------------- |
| `token`        | Your client authorization token. |
| `Content-Type` | Must be `application/json`.      |

***

### 🧪 Example Request

```bash
curl --location --request PATCH 'https://{API_URL}/api/policies/5' \
--header 'token: your-client-token' \
--header 'Content-Type: application/json' \
--data '{
    "permissions": {
        "userGroups": {
            "_p": 15
        }
    }
}'
```

#### Explanation

This example updates only the `userGroups` portion of the permissions.\
All other permission data in the policy stays exactly as it was.

***

### ⚙️ Notes

* The change is **backward compatible** — you can still use the full `PUT` request if needed.
* The new `PATCH` endpoint is now the **recommended way** to update policies.
* This update improves speed and reduces timeouts for policies with large permission sets.