TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-04-16 11:31:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
zitadel/docs/docs/apis/v3.mdx
Jan-Frederic Schubert 4101e1cd49
chore(docs): Migrate from Docusaurus v2 to v3 (#8036) 
Migrate Docs to latest version of Docusaursu (3.3.2 as of time of
writing)

---------

Co-authored-by: Florian Forster <florian@zitadel.com>
2024-06-20 12:55:03 +00:00

340 lines
12 KiB
Plaintext
Raw Blame History

---
title: APIs V3 (Preview)
---
import DocCardList from '@theme/DocCardList';
import CodeBlock from '@theme/CodeBlock';
import ActionServiceProto from '!!raw-loader!./_v3_action_service.proto'
import ActionExecutionProto from '!!raw-loader!./_v3_action_execution.proto'
import ActionTargetProto from '!!raw-loader!./_v3_action_target.proto'
import ActionSearchProto from '!!raw-loader!./_v3_action_search.proto'
import IDPServiceProto from '!!raw-loader!./_v3_idp_service.proto'
import IDPProto from '!!raw-loader!./_v3_idp.proto'
import IDPSearchProto from '!!raw-loader!./_v3_idp_search.proto'
import IDPGitLabProto from '!!raw-loader!./_v3_idp_gitlab.proto'
import LanguageServiceProto from '!!raw-loader!./_v3_language_service.proto'
import LanguageProto from '!!raw-loader!./_v3_language.proto'
import ObjectProto from '!!raw-loader!./_v3_object.proto'
import ResourceObjectProto from '!!raw-loader!./_v3_resource_object.proto'
import SettingsObjectProto from '!!raw-loader!./_v3_settings_object.proto'
The APIs described in this section are currently either in *Preview* stage or not implemented, yet.
Before using these APIs, pleases consider the [API release policy below](#api-release-policy)
## We Appreciate your Help
We invite you to...
- ... [discuss the concept with the ZITADEL community on GitHub](https://github.com/zitadel/zitadel/discussions/8125).
- ... try the implementations and provide feedback [by filing issues on GitHub](https://github.com/zitadel/zitadel/issues/new/choose).
## The Ideas behind the New V3 APIs
The current ZITADEL *GA* APIs are structured around contexts like System, Admin, Management, and Auth.
This structure leads to duplicate methods and makes it hard to find the right API for the right task.
Especially interacting with resources from multiple organizations is cumbersome.
Also, the APIs evolved over time, which lead to inconsistencies and a lack of flexibility in development.
We address these issues with the following new API categories:
- [Standard Resources](#standard-resources)
- [Reusable Resources](#reusable-resources)
- [Settings](#settings)
The designs for the new API categories aim for the following improvements:
### Service Structure
Instead of structuring the API methods around contexts, new APIs are structured around resources and settings.
This means, eventually, we deprecate the old System-, Admin-, Management- and AuthAPIs in favor of User-, Action-, Language-, FeatureAPIs and so on.
This change makes it easier to find the right API for the right task, especially for multi-organization resources.
Also, it allows for faster development and independent versioning of the APIs.
### Multitenancy Management and Consistency
To improve managing and reusing resources and settings in multitenancy scenarios, we define some rules for the new APIs:
- Single properties from instance settings are overridable (patchable) in organizations.
- Some settings support user-defined custom properties that are also overridable in organizations.
- Improved experience with reusing resources in multiple organizations and instances.
- Resources are searchable over all organizations with a single call by default.
### HTTP and gRPC Consistency
To make the APIs more consistent and easier to use, we follow the same patterns in all Proto files.
- Patching is favored over updating resources and settings.
- HTTP calls are mapped so that query parameters can be used as much as possible. We avoid the annotation `body: "*"`.
- For search performance, we enforce query limits.
## Standard Resources
Standard resources exist in exactly one context.
For example, a user is always assigned to exactly one organization.
Or one SMS provider is always assigned to exactly one instance.
Standard resource methods behave like this:
- Search request results can be scoped to a RequestContext.
- Search request results only contain results for which the requesting user has the necessary read permissions.
- Search requests are limited to 100 by default. The limit can be increased by the caller up to 1000 by default.
- Resource configurations are partially updatable. With HTTP, this is done via PATCH requests. If no changes were made, the response is successful.
- Status changes or other actions on resources with side effects are done via POST requests. Their HTTP path ends with the underscore prefixed action name. For example `POST /resources/users/{id}/_unlock`.
For a full proto example, have a look at the [ZITADELActions service](#zitadelactions).
## Reusable Resources
Reusable resources are like standard resources but can be reused in multiple contexts.
For example, an external identity provider can be defined once on the instance.
Each organization within this instance can then choose to use this identity provider or not.
Additionally to the methods described for standard resources, reusable have the following capabilities:
Reusable resources have the same behavior as standard resources with the following additions:
- Reusable resources can be created in a given context level (system, instance, org).
- For requests, that require a resource ID, no request context is needed.
- Reusable resources are available in child contexts, even if their state is *inactive*.
- The child context can control if an inherited resource should be active or inactive for itself using a state policy.
- In child contexts, the state policy of a reused resource is *inherit* by default and can be changed to *activate*, *deactivate* or back to *inherit*.
- In child contexts, a reused resources configuration is read-only.
- Child contexts can read at least the following properties of reused resources:
- ID
- name
- description
- state
- the state policy in the child context
- sequence
- last changed date
- parent context
- state in the immediate parent context.
- By default, search queries for reused resources return all resources from the given contexts, all inherited resources and all resources defined in all children contexts.
Typically, a new resource is first designed and implemented as a non-reusable resource.
If the community sees a benefit in reusing the resource in multiple contexts, reusability is added to the resource.
For a full proto example, have a look at the [ZITADELIdentityProviders service](#zitadelidentityproviders).
## Resource Services
All resource services by default support the following CRUD operations [as described above](#standard-resources-behavior).
- Create
- Read (get, search)
- Patch (partially update, success on no changes)
- Delete
### ZITADELActions
- Standard CRUD methods for Targets
- Standard CRUD methods for Executions except the PutExecution method replaces the CreateExecution and PatchExecution methods
Additional to the standard CRUD methods:
- ListAvailableExecutionServices
- ListAvailableExecutionMethods
- ListAvailableExecutionFunctions
\<details><summary>action_service.proto</summary>
<CodeBlock language="protobuf">{ActionServiceProto}</CodeBlock>
\</details>
\<details><summary>action_target.proto</summary>
<CodeBlock language="protobuf">{ActionTargetProto}</CodeBlock>
\</details>
\<details><summary>action_execution.proto</summary>
<CodeBlock language="protobuf">{ActionExecutionProto}</CodeBlock>
\</details>
\<details><summary>action_query.proto</summary>
<CodeBlock language="protobuf">{ActionSearchProto}</CodeBlock>
\</details>
### ZITADELUsers
Standard CRUD methods
### ZITADELUserSchemas
Standard CRUD methods
### ZITADELIdentityProviders
- Standard CRUD and methods for all IDPs
- Resources have additional properties for reusability capabilities.
\<details><summary>idp_service.proto</summary>
<CodeBlock language="protobuf">{IDPServiceProto}</CodeBlock>
\</details>
\<details><summary>idp.proto</summary>
<CodeBlock language="protobuf">{IDPProto}</CodeBlock>
\</details>
\<details><summary>idp_search.proto</summary>
<CodeBlock language="protobuf">{IDPSearchProto}</CodeBlock>
\</details>
\<details><summary>idp_gitlab.proto</summary>
<CodeBlock language="protobuf">{IDPGitLabProto}</CodeBlock>
\</details>
\<details><summary>object.proto</summary>
<CodeBlock language="protobuf">{ObjectProto}</CodeBlock>
\</details>
\<details><summary>resource_object.proto</summary>
<CodeBlock language="protobuf">{ResourceObjectProto}</CodeBlock>
\</details>
### ZITADELInstances
Additional to the standard CRUD methods:
- Limit (partial update of block and audit log retention)
- BulkLimit (partial update of block and audit log retention for multiple instances)
### ZITADELOrganizations
Additional to the standard CRUD methods:
- SetAsInstanceDefault
- GetInstanceDefault
### ZITADELDomains
Additional to the standard CRUD methods:
- SetAsPrimary
- Validate
### ZITADELSessions
Standard CRUD methods
### ZITADELProjects
Standard CRUD methods
### ZITADELApps
Standard CRUD methods
### ZITADELMemberships
The given context defines the organization, instance or system where the membership is created.
The context and the user ID together are unique.
Additional to the standard CRUD methods:
- ListAvailableRoles (context-aware)
### ZITADELGrants
- Standard CRUD methods for project grants
- Standard CRUD methods for user grants
- Standard CRUD methods for roles
### ZITADELSMTPProviders
Standard CRUD methods
### ZITADELSMSProviders
Standard CRUD methods
## Settings
Settings have no identity (ID) and are always context-aware.
They also don't have a state like active or inactive.
They only have properties that can be set and queried.
These properties are inherited to from parent-contexts (instance) to child-contexts (organization).
Settings behave like this:
- Setting and retrieving settings is always context-aware. By default, the context is the instance discovered by the requests *Host* header.
- All settings properties can be partially overridden in child-contexts.
- All settings properties can be partially reset in child-contexts, so their values default to the parent contexts property values.
- All settings properties returned by queries contain the value and if it is inherited, the context where it is inherited from.
For a full proto example, have a look at the [ZITADELLanguageSettings service](#zitadellanguagesettings).
## Settings Services
### ZITADELLanguageSettings
Default language, restricted languages, supported languages
\<details><summary>language_service.proto</summary>
<CodeBlock language="protobuf">{LanguageServiceProto}</CodeBlock>
\</details>
\<details><summary>language.proto</summary>
<CodeBlock language="protobuf">{LanguageProto}</CodeBlock>
\</details>
\<details><summary>object.proto</summary>
<CodeBlock language="protobuf">{ObjectProto}</CodeBlock>
\</details>
\<details><summary>settings_object.proto</summary>
<CodeBlock language="protobuf">{SettingsObjectProto}</CodeBlock>
\</details>
### ZITADELTextSettings
Key-value pairs for localized login texts, previously known as login texts
### ZITADELBrandingSettings
Predefined branding settings and custom key-value pairs, previously known as label policy or branding settings
### ZITADELLoginSettings
Previously known as login policy
### ZITADELLockoutSettings
Previously known as lockout policy
### ZITADELPasswordSettings
Previously known as password complexity policy
### ZITADELHelpSettings
Previously known as legal and support settings or privacy policy
### ZITADELDomainSettings
Previously known as domain policy
### ZITADELFeatureSettings
Feature toggles
Also contains disallow public org registrations on system and instance level.
### ZITADELTemplatesSettings
HTML and text templates for fully customizable emails and sms
### ZITADELSecretSettings
Replaces secret generators
## API Release Policy
- Defined but not yet implemented APIs are subject to change without further notice.
- Once an API definition is implemented, it is released as *Preview* and is available for testing.
- When a *Preview* API is tested enough so the concepts are proven to work, a new *Beta* API is released.
- When an API is feature-complete and stable enough, a new *GA* (General Availability) API is released.
- In all stages, changes to already implemented APIs are done in a backwards-compatible way, if possible.
- When we release a new stage for an API, we deprecate the previous stage and keep it available for a smooth transition.
## Preview APIs
These APIs are ready for testing and feedback.
Beware, they don't yet follow all the rules defined above.
<DocCardList />
Reference in New Issue View Git Blame Copy Permalink