From 65bb559bbec05cdb98539f6583766d653c916145 Mon Sep 17 00:00:00 2001 From: Iraq <66622793+kkrime@users.noreply.github.com> Date: Fri, 25 Apr 2025 14:04:29 +0200 Subject: [PATCH] docs(API_DESIGN.md): adding guidlines around API returns when multiple resources created (#9797) # Which Problems Are Solved Updating API_Design.md to include guidelines to specify all created resources created from an API call # How the Problems Are Solved This makes things clearer to the user if everything requested was actually created and helps with testing. See https://github.com/zitadel/zitadel/pull/9352 # Additional Context - Related https://github.com/zitadel/zitadel/issues/6305 - Related https://github.com/zitadel/zitadel/pull/9352 --------- Co-authored-by: Livio Spring --- API_DESIGN.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/API_DESIGN.md b/API_DESIGN.md index 7df13d6588..ea37df5a24 100644 --- a/API_DESIGN.md +++ b/API_DESIGN.md @@ -56,6 +56,10 @@ Provide clear and concise documentation for the API. Do not rely on implicit fallbacks or defaults if the client does not provide certain parameters. Only use defaults if they are explicitly documented, such as returning a result set for the whole instance if no filter is provided. +Some API calls may create multiple resources such as in the case of `zitadel.org.v2.AddOrganization`, where you can create an organization AND multiple users as admin. +In such cases the response should include **ALL** created resources and their ids. This removes any ambiguity from the users perspective whether or not +the additional resources were created and it also helps in testing. + ### Naming Conventions Names of resources, fields and methods MUST be descriptive and consistent. @@ -371,4 +375,4 @@ message VerifyEmailRequest{ ]; } -``` \ No newline at end of file +```