TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-05-06 09:06:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve apis description (#7400)

Browse Source 
* docs: improve apis description

* focus on version

* link to state
This commit is contained in:
Livio Spring 2024-02-19 15:39:36 +01:00 committed by GitHub
parent 0b77fd4c17
commit 462f5462dc
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 73 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/docs/apis/apis/index.mdx Normal file
View File

@ -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 />

2
docs/docs/apis/introduction.mdx
View File

@ -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)

12
docs/docs/apis/v2.mdx Normal file
View File

@ -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 />

15
docs/docs/apis/v3.mdx Normal file
View File

@ -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 />

8
docs/docs/support/software-release-cycles-support.md
View File

@ -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

88
docs/sidebars.js
View File

@ -521,38 +521,19 @@ module.exports = {
label: "Core Resources",
collapsed: false,
link: {
type: "generated-index",
title: "Core Resources",
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.",
type: "doc",
id: "apis/apis/index",
},
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:
"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.",
description: "APIs V1 organize access by context (authenticated user, organisation, instance, system), unlike resource-specific V2 APIs.",
},
items: [
{
@ -609,24 +590,11 @@ module.exports = {
},
{
type: "category",
label: "Resource Based (V2)",
label: "V2 (Beta)",
collapsed: false,
link: {
type: "generated-index",
title: "Resource Based 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.",
type: "doc",
id: "apis/v2",
},
items: [
{
@ -689,68 +657,52 @@ module.exports = {
},
{
type: "category",
label: "Resource Based (V3)",
label: "V3 (Preview)",
collapsed: false,
link: {
type: "generated-index",
title: "Resource Based 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.",
type: "doc",
id: "apis/v3",
},
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"),
},

4
proto/zitadel/execution/v3alpha/execution_service.proto
View File

@ -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";
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.";
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 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"

4
proto/zitadel/user/schema/v3alpha/user_schema_service.proto
View File

@ -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";
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.";
version: "3.0-preview";
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"

4
proto/zitadel/user/v3alpha/user_service.proto
View File

@ -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";
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.";
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 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"