Skip to content
65 changes: 56 additions & 9 deletions website/src/content/docs/docs/howtos/ARM/resource-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,22 @@ op get is ArmResourceRead<MyResource>;
- **get**: The name of the operation passed on to clients.
- **Resource**: A reference to your resource type.

### Resource Check Existence Operations (HEAD)

The check existence operation uses a HEAD request to efficiently determine whether a resource exists
without returning the resource body. This is useful when you only need to verify a resource's
existence and do not need to retrieve its full representation.

```typespec
op checkExistence is ArmResourceCheckExistence<MyResource>;
```

| Operation | TypeSpec |
| --------------- | ----------------------------------------------------------- |
| Check Existence | `checkExistence is ArmResourceCheckExistence<ResourceType>` |

This operation returns a 204 response if the resource exists, or a 404 response if it does not.

### Resource CreateOrUpdate Operations (PUT)

The CreateOrUpdate operation may be synchronous (The operation may always complete before a response
Expand Down Expand Up @@ -117,15 +133,25 @@ PATCH for Resource tags only, a PATCH for all updateable properties, or a custom
you should choose the patch for all updateable properties, unless you have a very good reason for
choosing another PATCH operation.

| Operation Description | TypeSpec |
| -------------------------- | ---------------------------------------------------------------- |
| Sync TagsOnly PATCH | `update is ArmTagsPatchSync<ResourceType>` |
| Async TagsOnly PATCH | `update is ArmTagsPatchAsync<ResourceType>` |
| Sync All Properties PATCH | `update is ArmCustomPatchSync<ResourceType, PatchRequestModel>` |
| Async All Properties PATCH | `update is ArmCustomPatchAsync<ResourceType, PatchRequestModel>` |

The ArmTagsPatch\* templates take the resource type as a parameter. The ArmCustomPatch\*
templates take the resource type and your custom PATCH request type as parameters.
| Operation Description | TypeSpec |
| ------------------------------------------- | ----------------------------------------------------------------------- |
| Sync TagsOnly PATCH | `update is ArmTagsPatchSync<ResourceType>` |
| Async TagsOnly PATCH | `update is ArmTagsPatchAsync<ResourceType>` |
| Sync Custom Properties PATCH (recommended) | `update is ArmCustomPatchSync<ResourceType, PatchRequestModel>` |
| Async Custom Properties PATCH (recommended) | `update is ArmCustomPatchAsync<ResourceType, PatchRequestModel>` |
| Sync Lifecycle PATCH | `update is ArmResourcePatchSync<ResourceType, ResourcePropertiesType>` |
| Async Lifecycle PATCH | `update is ArmResourcePatchAsync<ResourceType, ResourcePropertiesType>` |

The `ArmCustomPatch*` templates are the recommended choice for PATCH operations. They take the
resource type and your custom PATCH request type as parameters, giving you full control over the
PATCH schema. The `ArmTagsPatch*` templates take the resource type as a parameter and only allow
updating ARM tags.

> **Note:** The `ArmResourcePatch*` templates are **not recommended**. They rely on Lifecycle.Update
> visibility analysis to automatically determine which properties are included in the PATCH schema,
> but this analysis is only performed by the typespec-autorest emitter and will not be replicated in
> SDKs generated for the PATCH operation. Instead, spec authors should define a specific PATCH model
> and use the `ArmCustomPatch*` templates.

### Resource Delete Operations (DELETE)

Expand Down Expand Up @@ -160,6 +186,11 @@ Arm Resource list operations return a list of Tracked or Proxy Resources at a pa
| ------------------ | ----------------------------------------------------------- |
| ListByParent | `listByWidget is ArmResourceListByParent<ResourceType>` |
| ListBySubscription | `listBySubscription is ArmListBySubscription<ResourceType>` |
| ListAtScope | `listAtScope is ArmResourceListAtScope<ResourceType>` |

The `ArmResourceListAtScope` template is used when the scope of the list operation is determined by
the `BaseParameters` type parameter. This is useful for resources with custom scope requirements
that do not fit the standard parent or subscription scopes.

### Resource Actions (POST)

Expand Down Expand Up @@ -208,6 +239,22 @@ described in the next section of the document:
- [Synchronous Resource List Actions](#synchronous-list-action)
- [Asynchronous List Action](#asynchronous-list-action)

### Provider Actions (POST)

Provider actions are operations that are not scoped to a specific resource instance but instead
operate at the provider level. These are useful for operations like performing tenant-wide
configuration or subscription-level actions that are not tied to a particular resource.

| Operation | TypeSpec |
| --------------------------------- | ------------------------------------------------------------------------------- |
| Synchronous Provider Action | `myAction is ArmProviderActionSync<Request, Response>` |
| Asynchronous Provider Action | `myAction is ArmProviderActionAsync<Request, Response>` |
| Provider Action with custom scope | `myAction is ArmProviderActionSync<Request, Response, SubscriptionActionScope>` |
| Provider Action with no request | `myAction is ArmProviderActionSync<void, Response>` |

By default, provider actions use `TenantActionScope`. You can specify a different scope such as
`SubscriptionActionScope` or `ExtensionResourceActionScope` using the `Scope` template parameter.

### Check Name Operations

Some services provide operations to check name availability, either location-specific (locally) or
Expand Down