AGENT-DRAFT: CJ-4081 — Tag Key Migration [code+dev-draft]

docs/apim/4.11/reference/data-model/README.md

@@ -0,0 +1 @@
+# Data Model

docs/apim/4.11/reference/data-model/tag-entity-schema-and-key-field-reference.md

@@ -0,0 +1,80 @@
+# Tag entity schema and key field reference
+
+<!-- DISCREPANCY: This page was placed in 4.11 by the agent, but the feature is merged in APIM 4.12.x only (confirmed by Okhelifi and verified from git history + Liquibase v4_12_0 directory). Move this file to docs/apim/4.12/ once that folder exists. -->
+
+## Overview
+
+Starting in APIM 4.12, each tag has a dedicated `key` field that separates the human-readable tag identifier from the internal `id`. This affects how tags are referenced in REST API endpoints and how new tags are created.
+
+For existing tags, the migration preserves the current `id` value and copies it into the new `key` field. This means existing API clients continue to work without changes. Only new tags created after migration receive a UUID as their `id`.
+
+<!-- Verified from TagKeyUpgrader.java: tag.setKey(tag.getId()) — existing IDs are preserved, not regenerated. Confirmed by Okhelifi. -->
+
+## Tag fields
+
+| Field | Format | Purpose | Example |
+|:------|:-------|:--------|:--------|
+| `id` | String | Internal database reference. For existing tags, this retains the original value. For new tags, this is a UUID. | `70237305-6f68-450e-a373-056f68750e50` |
+| `key` | String (max 64 chars) | User-facing identifier used in API operations and path parameters | `international` |
+| `name` | String (max 64 chars) | Display name (unique within the reference scope) | `International` |
+| `description` | String | Optional tag description | — |
+| `restrictedGroups` | Array of strings | Optional list of groups with access to this tag | — |
+
+When creating a tag, provide both `key` and `name` (each 1–64 characters). The `key` field is immutable after creation.
+
+<!-- Verified from UpdateTagEntity.java: no key field exists in the update DTO. TagServiceImpl preserves the key on update via .key(existingTag.getKey()). -->
+
+## REST API endpoints
+
+All tag management endpoints use the tag `key` in path parameters.
+
+| Endpoint | Method | Path | Notes |
+|:---------|:-------|:-----|:------|
+| List tags | GET | `/tags` | Returns all tags |
+| Get tag | GET | `/tags/{tagKey}` | Retrieve a single tag by key |
+| Create tag | POST | `/tags` | Include `key` and `name` in the request body |
+| Update tag | PUT | `/tags/{tagKey}` | Accepts `name`, `description`, and `restrictedGroups` only |
+| Delete tag | DELETE | `/tags/{tagKey}` | Delete a tag by key |
+
+<!-- Verified from TagsResource.java: GET /tags, GET /tags/{tag}, POST /tags, PUT /tags/{tag}, DELETE /tags/{tag}. All path params reference the key. -->
+
+### Create a tag
+
+Send a POST request to `/tags` with the following fields:
+
+- `key` (required, 1–64 characters): immutable tag identifier
+- `name` (required, 1–64 characters): display name, unique within the reference scope
+- `description` (optional)
+- `restrictedGroups` (optional array)
+
+The system generates a UUID for the internal `id` field. If a tag with the same `key` already exists, the request fails.
+
+<!-- Verified: DuplicateTagKeyException is thrown on duplicate key (TagServiceImpl.java line 142). -->
+
+### Update a tag
+
+Send a PUT request to `/tags/{tagKey}` with `name`, `description`, and `restrictedGroups`. The request body doesn't accept `id` or `key` fields.
+
+### Delete a tag
+
+Send a DELETE request to `/tags/{tagKey}`.
+
+## Behavior for existing vs. new tags
+
+{% hint style="info" %}
+For **existing tags**, the migration preserves the original `id` value and sets `key` to the same value. Existing API clients that reference tags by their current ID in path parameters continue to work, because the `key` matches the old `id`.
+
+For **new tags** created after migration, the `id` is a generated UUID. API clients interact with new tags using the `key` field in path parameters, not the UUID.
+{% endhint %}
+
+<!-- DISCREPANCY: The original agent draft stated "existing API clients using tag IDs will fail" — this is incorrect. Okhelifi confirmed existing IDs are preserved and the key equals the old ID. Only new tags use UUIDs as IDs. -->
+
+## Restrictions
+
+- Tag keys are immutable after creation.
+- Tag names are unique within the same reference scope.
+- The `key` field is limited to 64 characters.
+
+## Related
+
+- [Tag key migration upgrade procedure](../../upgrade-guides/tag-key-migration-upgrade-procedure.md)

docs/apim/4.11/upgrade-guides/tag-key-migration-upgrade-procedure.md

@@ -0,0 +1,51 @@
+# Tag key migration upgrade procedure
+
+<!-- DISCREPANCY: This page was placed in 4.11 by the agent, but the feature is merged in APIM 4.12.x only (confirmed by Okhelifi and verified from git history + Liquibase v4_12_0 directory). Move this file to docs/apim/4.12/ once that folder exists. -->
+
+## Overview
+
+When upgrading to APIM 4.12, an automated migration adds a `key` field to all existing tags. This migration runs once during the platform upgrade and doesn't require manual intervention.
+
+## What the migration does
+
+The migration runs automatically during startup (execution order 716). For each existing tag, it:
+
+1. Reads the current `id` value.
+2. Copies that `id` value into the new `key` field.
+3. Saves the updated tag.
+
+Existing tag IDs aren't changed. This preserves backward compatibility and allows rollback to a previous APIM version without database conflicts.
+
+<!-- Verified from TagKeyUpgrader.java: tag.setKey(tag.getId()) — the ID is preserved, not regenerated as a UUID. Confirmed by Okhelifi: "to allow customer to rollback to a previous APIM version, during the migration the existing tags will keep the same ids." -->
+
+**Example:**
+
+```text
+Before migration:
+Tag { id: "international", key: null, name: "International" }
+
+After migration:
+Tag { id: "international", key: "international", name: "International" }
+```
+
+Only new tags created after migration receive a UUID as their `id`.
+
+## Prerequisites
+
+- The database schema includes the `tags.key` column, added automatically via Liquibase migration (`v4_12_0/00_add_tags_key_column.yml`).
+
+<!-- Verified: Liquibase changelog is at gravitee-apim-repository-jdbc/src/main/resources/liquibase/changelogs/v4_12_0/00_add_tags_key_column.yml. Agent draft incorrectly referenced "09_add_tags_key_column.yml". -->
+
+## Post-migration changes
+
+After migration:
+
+- All tag REST API endpoints use the tag `key` in path parameters instead of the `id`. For existing tags, the `key` equals the old `id`, so existing API calls continue to work.
+- New tags created via the API require a `key` field in the request body.
+- API clients that create new tags and store the `id` for later reference need to use the `key` for subsequent operations (GET, PUT, DELETE), not the UUID `id`.
+
+For the full list of affected endpoints, see [Tag entity schema and key field reference](../reference/data-model/tag-entity-schema-and-key-field-reference.md#rest-api-endpoints).
+
+{% hint style="info" %}
+If the migration encounters an error, it logs a failure message and the platform continues to start. Check the application logs for details and contact support if tag operations don't work as expected after upgrade.
+{% endhint %}

docs/gravitee-cloud/guides/gravitee-hosted-gateways/README.md

@@ -17,7 +17,7 @@ A full SaaS set up of Gravitee is a convenient way to run Gravitee. Gravitee man
 ## Deploy a Gravitee hosted Gateway
 
 {% hint style="info" %}
-You do not have to scale your Gateways. Gravitee scales your Gateways and manages high availability.
+You don't have to scale your Gateways. Gravitee scales your Gateways and manages high availability.
 {% endhint %}
 
 ### Add Gateway details
@@ -43,10 +43,10 @@ When deploying a new Gateway, you can optionally set sharding tags. To add shard
 1.  Navigate to the **Deployment Tags** section.
 
     <figure><img src="../../.gitbook/assets/deployment-tags-cloud-version.png" alt=""><figcaption></figcaption></figure>
-2.  In the **Sharding Tags IDs** field, enter one or more tags that identify this Gateway's purpose. For example, "us-east", "production", "eu-west".
+2.  In the **Sharding Tags Keys** field, enter one or more tags that identify this Gateway's purpose. For example, `us-east`, `production`, `eu-west`.
 
     <figure><img src="../../.gitbook/assets/sharding-tag-ids-cloud.png" alt=""><figcaption></figcaption></figure>
-3.  In the **Tenant Tags** field, input identifiers that represent the backend services or tenants the Gateway should route to. For example, "eu-west-1".
+3.  In the **Tenant Tag Keys** field, enter identifiers that represent the backend services or tenants the Gateway routes to. For example, `eu-west-1`.
 
     <figure><img src="../../.gitbook/assets/tenant-tag-ids-description.png" alt=""><figcaption></figcaption></figure>
 4. Click **Save**.
@@ -64,7 +64,7 @@ When deploying a new Gateway, you can optionally set sharding tags. To add shard
    4.  Choose the region for your Gateway
 
        <figure><img src="../../.gitbook/assets/deploy-gateway-2.png" alt=""><figcaption></figcaption></figure>
-3. (Optional) Add development tags. For morei nformation about adding development tags, see [#optional-add-development-tags](./#optional-add-development-tags "mention").
+3. (Optional) Add development tags. For more information about adding development tags, see [#optional-add-development-tags](./#optional-add-development-tags "mention").
 4.  Click on **Save.**
 
     <figure><img src="../../.gitbook/assets/click-on-save.png" alt=""><figcaption></figcaption></figure>
@@ -149,7 +149,7 @@ Gateway tagging is handled in the Cloud UI deployment process. For API configura
 * [Add sharding tags to your APIs](https://documentation.gravitee.io/apim/configure-and-manage-the-platform/gravitee-gateway/sharding-tags#add-sharding-tags-to-your-apis)
 
 {% hint style="danger" %}
-**Note:** Skip any steps involving `gravitee.yml`, `values.yaml`, or environment variables. These are not applicable to Gravitee-hosted gateways.
+**Note:** Skip any steps involving `gravitee.yml`, `values.yaml`, or environment variables. These aren't applicable to Gravitee-hosted gateways.
 {% endhint %}
 
 #### Configure Tenant Tags in API Management

vale/styles/config/vocabularies/docs/accept.txt

@@ -351,7 +351,7 @@ ISO
 # ============================================
 # Gravitee-Specific Features & Config
 # ============================================
-[Ss]harding.tags?
+[Ss]harding.[Tt]ags?
 [Ee]ntrypoint
 gravitee\.yml
 gravitee\.yaml