From Persona-based to Resource-based: Rethinking ZITADELs API Design

We decided to adopt a resource-based API for ZITADEL in response to feedback from our customers and community members. Our overarching goal has always been to provide an exceptional experience for developers using our platform. However, through ongoing conversations with users, we came to the understanding that while some of our architecture and design decisions were technically sound, they didn't necessarily translate into an intuitive and user-friendly experience from a developer's perspective.

Our API design was identified as one area where we could significantly enhance the developer experience. By transitioning to a resource-based API, we are making our system more intuitive and easy to understand. A resource-based API structure focuses on "resources" as the main entities, as opposed to methods or operations, which aligns better with the way developers think about their interactions with our platform. We believe this change will make ZITADEL more approachable and enjoyable for developers to use.

Persona-based API design

ZITADEL's API design is grounded in the concept of personas, each with different use cases. The distinct APIs cater to these various personas and their specific needs, creating a more personalized and intuitive interface. For instance, the Authentication API is designed primarily for currently authenticated users. Therefore, if you're developing a user profile or settings page for authenticated users, the Authentication API would be your main resource.

Similarly, different APIs are designated for different roles. The Management API is accessible to the administrator of an organization, while the Admin API is available for the IAM administrator.

At first glance, the division of responsibilities and access based on roles appears to make a lot of sense. However, when we take into account how developers typically interact with our platform, potential complications become evident. It's not uncommon for developers to dive straight into implementation without thoroughly studying the documentation.

Let's take an example: a developer wants to create a settings page for a user and needs to retrieve the user information. They would go to the API documentation and search for "get user". This seemingly simple query returns multiple results, each tied to a different API and with different permissions:

• Auth API: "Get my own user"
• Management API: "Get user by ID from my organization"
• Admin API: "Get user by ID from any organization"

Without proper understanding of the differences between these APIs, developers may become confused and unsure about which option is the right one for their needs. This is the kind of complication we aim to reduce with our new API design.

Resource-based API design

After considering all the above factors, we have concluded that a resource-based API is significantly more straightforward to understand than a persona-based API.

By "resource-based API", we mean an API that allows access to the various resources ZITADEL provides, irrespective of the user's role or persona. The fundamental principle here is that users access resources through a single API, and the depth or breadth of the results they see depends on the permissions of the user making the request. This design simplifies the user's navigation through the API and makes for a more intuitive experience.

Let's take an example of how this resource-based API design works. Let's say we have a 'users' resource in the API. This resource supports various operations such as create, update, delete, get by ID, and search for users.

• If I'm an end user, and I request a 'get by id' operation, the API will only permit me to retrieve my own user information, respecting the principle of least privilege.

• If I'm an administrator of an organization, I can utilize the 'search users' operation to retrieve details of all users within my organization, representing a higher level of access.

• Finally, if I'm an Identity and Access Management (IAM) administrator, I can use the 'search users' operation to access information on users across any organization in the system, reflecting the highest level of access.

This approach simplifies interactions by centralizing operations on a single resource, while still maintaining appropriate access control based on the user's role.

Our Progress and Future Plans

We have already made considerable progress with the new API. All the necessary requests to construct your own login and registration UI have been implemented. As we continue to expand this new API, we will add new requests and gradually transition existing requests from the previous APIs (Auth, Management, Admin) to this new, resource-based API.

With the full implementation of this new API design, we are confident that we will significantly enhance the developer experience. We believe that these changes will simplify not only our customers' experience but also streamline our own operations. We look forward to offering a more efficient, user-friendly platform thanks to this resource-based API design.

Stay tuned for more updates!

Read the API Documentation

See the documentation of the currently available API resources of the new API if you want to learn more right away.

• User
• Session
• Settings
• OIDC