docs: improve apis description (#7400)

* docs: improve apis description

* focus on version

* link to state

docs/docs/apis/apis/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Core Resources
+sidebar_label: Core Resources
+---
+
+import DocCardList from '@theme/DocCardList';
+
+ZITADEL provides multiple APIs to manage the system, instances and resources such as users, projects and more.
+
+There are different versions and multiple services available:
+
+<DocCardList />

docs/docs/apis/introduction.mdx

@@ -39,7 +39,7 @@ Refer to our guide to learn how to [build your own login UI](/docs/guides/integr
 
 ## ZITADEL APIs (resource-based)
 
-ZITADEL provides APIs for each [core resource](/docs/apis/resources):
+ZITADEL provides APIs for each [core resource](/docs/apis/v2):
 
 - [User](/docs/apis/resources/user_service)
 - [Session](/docs/apis/resources/session_service)

docs/docs/apis/v2.mdx

@@ -0,0 +1,12 @@
+---
+title: APIs V2 (Beta)
+---
+
+import DocCardList from '@theme/DocCardList';
+
+APIs V2 organize access by resources (users, settings, etc.), unlike context-specific V1 APIs.
+This simplifies finding the right API, especially for multi-organization resources.
+
+**Note**: V2 is currently in [Beta](/support/software-release-cycles-support#beta) and not yet generally available (breaking changes possible). Check individual services for availability.
+
+<DocCardList />

docs/docs/apis/v3.mdx

@@ -0,0 +1,15 @@
+---
+title: APIs V3 (Preview)
+---
+
+import DocCardList from '@theme/DocCardList';
+
+APIs (V3) organize access by resources (users, settings, etc.), unlike context-specific V1 APIs.
+This simplifies finding the right API, especially for multi-organization resources.
+V3 also offers more flexibility over the V2 API in these points:
+- User schema definition for custom user management.
+- Behavior customization (API call manipulation, webhooks).
+
+**Note**: V3 is currently in [Preview](/support/software-release-cycles-support#preview) and not yet generally available (breaking changes possible). Check individual services for availability.
+
+<DocCardList />

docs/docs/support/software-release-cycles-support.md

@@ -51,7 +51,13 @@ Therefore, it's recommended to use caution when using Alpha and Beta software, a
 
 Only features in General Availability will be covered by support services.
 
-We encourage our community to test Alpha and Beta software and provide feedback via our [Discord Chat](https://zitadel.com/chat).
+We encourage our community to check out Preview and test Alpha and Beta software and provide feedback via our [Discord Chat](https://zitadel.com/chat).
+
+### Preview
+
+The Preview state is our initial stage to document planned futures and collect early feedback on the design.
+Features are not yet implemented at all or availability is limited to designated testers.
+We recommend that users exercise caution when using Preview software and avoid using it for critical tasks, as support is limited during this phase.
 
 ### Alpha
 

docs/sidebars.js

@@ -521,38 +521,19 @@ module.exports = {
       label: "Core Resources",
       collapsed: false,
       link: {
-        type: "generated-index",
+        type: "doc",
-        title: "Core Resources",
+        id: "apis/apis/index",
-        slug: "/apis/apis/",
-        description:
-            "ZITADEL provides multiple APIs to manage the system, instances and resources such as users, projects and more.\n" +
-            "\n" +
-            "There are multiple different versions and multiple services available:"+
-            "\n" +
-            "The resource based APIs are, as the name suggests, organized by resources such as users, session, settings and more.\n" +
-            "These services are the future of the ZITADEL APIS and the best way to start integrating ZITADEL.\n" +
-            "\n"+
-            "The service based APIs are organized by UseCase/Context, such as Auth API for authenticated users,"+
-            "Management API for organization managers, Admin API for instance managers and a System API for system managers.",
       },
       items: [
         {
           type: "category",
-          label: "Service Based (V1)",
+          label: "V1 (General Available)",
           collapsed: false,
           link: {
             type: "generated-index",
-            title: "Service Based APIs (V1)",
+            title: "APIs V1 (GA)",
             slug: "/apis/services/",
-            description:
+            description: "APIs V1 organize access by context (authenticated user, organisation, instance, system), unlike resource-specific V2 APIs.",
-                "The service based APIs are organized by UseCase/Context, such as Auth API for authenticated users,"+
-                "Management API for organization managers, Admin API for instance managers and a System API for system managers.\n"+
-                "\n"+
-                "To improve the developer experience in managing the different resources, ZITADEL also offers Resource Based APIs (v2 and v3). "+
-                "Those APIs focus on the resources themselves. For example they offer a User Service, which will give you the possibility " +
-                "to search for users across multiple organizations.\n"+
-                "Note that the Resource Based APIs are not yet generally available. Please check the corresponding service" +
-                "for their state and functionality.",
           },
           items: [
             {
@@ -609,24 +590,11 @@ module.exports = {
         },
         {
           type: "category",
-          label: "Resource Based (V2)",
+          label: "V2 (Beta)",
           collapsed: false,
           link: {
-            type: "generated-index",
+            type: "doc",
-            title: "Resource Based APIs (V2)",
+            id: "apis/v2",
-            slug: "/apis/resources/",
-            description:
-                "The resource based APIs are, as the name suggest, organized by resources such as users, session, settings and more. "+
-                "Check the list below to get an overview of all available resources.\n"+
-                "\n"+
-                "While the service based APIs (V1) work great for use cases in a specific context such as a single organization, " +
-                "it's sometime difficult to know which API to use, particularly for resources across multiple organizations. "+
-                "For instance, SearchUsers on an Instance level or on an Organization level.\n"+
-                "This is exactly where the resource based APIs come in place, e.g. with the User Service, " +
-                "where you're able to search all users and can provide the context (organization) yourself if needed or just search the whole instance.\n"+
-                "\n"+
-                "Note that these APIs are not yet generally available and therefore breaking changes might still occur.\n"+
-                "Please check the corresponding service for more information on the state and availability.",
           },
           items: [
             {
@@ -689,68 +657,52 @@ module.exports = {
         },
         {
           type: "category",
-          label: "Resource Based (V3)",
+          label: "V3 (Preview)",
           collapsed: false,
           link: {
-            type: "generated-index",
+            type: "doc",
-            title: "Resource Based APIs (V3)",
+            id: "apis/v3",
-            slug: "/apis/resources_v3/",
-            description:
-                "The resource based APIs are, as the name suggests, organized by resources such as users, session, settings and more.\n"+
-                "\n"+
-                "While the service based APIs (V1) work great for use cases in a specific context such as a single organization, " +
-                "it's sometime difficult to know which API to use, particularly for resources across multiple organizations. "+
-                "For instance, SearchUsers on an Instance level or on an Organization level.\n"+
-                "This is exactly where the resource based APIs come in place, e.g. with the User Service, " +
-                "where you're able to search all users and can provide the context (organization) yourself if needed or just search the whole instance.\n"+
-                "\n"+
-                "Version 3 offers more customization than the V2 resource bases APIs. You can define your own user schema "+
-                "to be able to manage users based on these schemas and customize various behaviors, such as manipulating "+
-                "inbound API calls, call webhooks on different event and more with the execution service.\n"+
-                "\n"+
-                "Note that these APIs are not yet generally available and therefore breaking changes might still occur.\n"+
-                "Please check the corresponding service for more information on the state and availability.",
           },
           items: [
             {
               type: "category",
-              label: "User Schema Lifecycle (Alpha)",
+              label: "User Schema Lifecycle (Preview)",
               link: {
                 type: "generated-index",
-                title: "User Schema Service API (Aplha)",
+                title: "User Schema Service API (Preview)",
                 slug: "/apis/resources/user_schema_service",
                 description:
                     "This API is intended to manage data schemas for users in a ZITADEL instance.\n" +
                     "\n" +
-                    "This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.",
+                    "This project is in Preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.",
               },
               items: require("./docs/apis/resources/user_schema_service_v3/sidebar.js"),
             },
             {
               type: "category",
-              label: "User Lifecycle (Alpha)",
+              label: "User Lifecycle (Preview)",
               link: {
                 type: "generated-index",
-                title: "User Service API (Aplha)",
+                title: "User Service API (Preview)",
                 slug: "/apis/resources/user_service_v3",
                 description:
                     "This API is intended to manage users with your own data schema in a ZITADEL instance.\n"+
                     "\n"+
-                    "This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services."
+                    "This project is in Preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services."
               },
               items: require("./docs/apis/resources/user_service_v3/sidebar.js"),
             },
             {
               type: "category",
-              label: "Execution Lifecycle (Alpha)",
+              label: "Execution Lifecycle (Preview)",
               link: {
                 type: "generated-index",
-                title: "Execution Service API (Alpha)",
+                title: "Execution Service API (Preview)",
                 slug: "/apis/resources/execution_service_v3",
                 description:
                     "This API is intended to manage custom executions (previously known as actions) in a ZITADEL instance.\n"+
                     "\n"+
-                    "This project is in alpha state. It can AND will continue breaking until the services provide the same functionality as the current actions.",
+                    "This project is in Preview state. It can AND will continue breaking until the services provide the same functionality as the current actions.",
               },
               items: require("./docs/apis/resources/execution_service_v3/sidebar.js"),
             },

proto/zitadel/execution/v3alpha/execution_service.proto

@@ -17,8 +17,8 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/execution/v3alpha;execu
 option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   info: {
     title: "Execution Service";
-    version: "3.0-alpha";
+    version: "3.0-preview";
-    description: "This API is intended to manage custom executions (previously known as actions) in a ZITADEL instance. This project is in alpha state. It can AND will continue breaking until the services provide the same functionality as the current actions.";
+    description: "This API is intended to manage custom executions (previously known as actions) in a ZITADEL instance. This project is in preview state. It can AND will continue breaking until the services provide the same functionality as the current actions.";
     contact:{
       name: "ZITADEL"
       url: "https://zitadel.com"

proto/zitadel/user/schema/v3alpha/user_schema_service.proto

@@ -18,8 +18,8 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/user/schema/v3alpha";
 option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   info: {
     title: "User Schema Service";
-    version: "3.0-alpha";
+    version: "3.0-preview";
-    description: "This API is intended to manage data schemas for users in a ZITADEL instance. This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
+    description: "This API is intended to manage data schemas for users in a ZITADEL instance. This project is in preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
     contact:{
       name: "ZITADEL"
       url: "https://zitadel.com"

proto/zitadel/user/v3alpha/user_service.proto

@@ -21,8 +21,8 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/user/v3alpha";
 option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   info: {
     title: "User Service";
-    version: "3.0-alpha";
+    version: "3.0-preview";
-    description: "This API is intended to manage users with your own data schema in a ZITADEL instance. This project is in alpha state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
+    description: "This API is intended to manage users with your own data schema in a ZITADEL instance. This project is in preview state. It can AND will continue breaking until the service provides the same functionality as the v1 and v2 user services.";
     contact:{
       name: "ZITADEL"
       url: "https://zitadel.com"