From 6929c680c4d99ab4a0700ea8a33e13fc49ca817d Mon Sep 17 00:00:00 2001
From: Elio Bischof <elio@zitadel.com>
Date: Tue, 20 May 2025 16:14:30 +0200
Subject: [PATCH] docs: specify deprecations (#9915)

# Which Problems Are Solved

We have no standard way of deprecating API methods.

# How the Problems Are Solved

The API_DESIGN.md contains a section that describes how to deprecate
APIs.
Most importantly, deprecated APIs should link to replacement APIs for
good UX.

# Additional Context

- [x] Discussed with @stebenz during review of
https://github.com/zitadel/zitadel/pull/9743#discussion_r2081736144
- [ ] Inform backend engineers when this is merged.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 API_DESIGN.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/API_DESIGN.md b/API_DESIGN.md
index ac7c4a01e0..9e77657ab0 100644
--- a/API_DESIGN.md
+++ b/API_DESIGN.md
@@ -48,6 +48,52 @@ When creating a new service, start with version `2`, as version `1` is reserved
 
 Please check out the structure Buf style guide for more information about the folder and package structure: https://buf.build/docs/best-practices/style-guide/
 
+### Deprecations
+
+As a rule of thumb, redundant API methods are deprecated.
+
+- The proto option `grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation.deprecated` MUST be set to true.
+- One or more links to recommended replacement methods MUST be added to the deprecation message as a proto comment above the rpc spec.
+- Guidance for switching to the recommended methods for common use cases SHOULD be added as a proto comment above the rpc spec.
+
+#### Example
+
+```protobuf
+// Delete the user phone
+//
+// Deprecated: [Update the user's phone field](apis/resources/user_service_v2/user-service-update-user.api.mdx) to remove the phone number.
+//
+// Delete the phone number of a user.
+rpc RemovePhone(RemovePhoneRequest) returns (RemovePhoneResponse) {
+  option (google.api.http) = {
+    delete: "/v2/users/{user_id}/phone"
+    body: "*"
+  };
+
+  option (zitadel.protoc_gen_zitadel.v2.options) = {
+    auth_option: {
+      permission: "authenticated"
+    }
+  };
+
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+    deprecated: true;
+    responses: {
+      key: "200"
+      value: {
+        description: "OK";
+      }
+    };
+    responses: {
+      key: "404";
+      value: {
+        description: "User ID does not exist.";
+      }
+    }
+  };
+}
+```
+
 ### Explicitness
 
 Make the handling of the API as explicit as possible. Do not make assumptions about the client's knowledge of the system or the API.