[DRAFT] Studio vision and plans

[fmvilas]

THIS IS A WORK IN PROGRESS

This issue aims to explain my vision and plans for AsyncAPI Studio. Please take this as an initial proposal. It's by no means set in stone and I'd love it if we could work on this together as a community.

Vision

Studio goes beyond a simple playground to try out the spec and becomes a fully-featured suite to help developers work with event-driven architectures (EDA) and APIs. It will become a tool you can use to easily design your services and share them with your colleagues. Among other features, it should:

• Let people quickly start authoring AsyncAPI documents without having to learn the AsyncAPI syntax and nuances. This is pretty important to encourage people to use AsyncAPI without having to go through the steep learning curve of learning the syntax. It would also help us evolve the syntax without having to worry too much about how it looks for humans and even make it easier to release new major versions of the spec. Not saying it solves the problem completely, it just helps :). Ideally, it will come to a point where devs don't have to learn the spec at all and many of them would never see how it looks like. Just like you don't edit a PDF file on your code editor and, instead, you open and edit them on a PDF editor, you shouldn't edit an AsyncAPI file by hand. It should just become an exchange format for tools and teams to work with EDAs and APIs.
• Let organizations make sense of their EDA. One of the biggest challenges I hear when I talk to people doing EDAs in production is figuring out how things are "connected together", finding channels where the information they need is being published, and knowing who are the people in charge of it. I always ask a question to people doing EDAs at scale: "If I make a breaking change in the payload of one of your messages, do you know who will be impacted?". The usual answer is "No, I have no idea and that's actually making the system break every so often". Even more, not understanding your EDA leads to duplication of resources. People are fearful to break stuff so instead of introducing a change in one of the existing messages, they create new channels where they publish this information just for themselves (often polling values on a database). This has a huge impact on the cost and complexity of the whole architecture, not to mention the environment.
• Help teams collaborate together. Independently of where you store your AsyncAPI files, there should be a place where you can find them all and search for the information you need. There are multiple tools and products to help you accomplish this: Backstage by Spotify, Event Catalog by @boyney123, Bump.sh, Solace, SwaggerHub, Postman, etc. Studio should not aim to replace or compete with these tools but instead integrate with them. Maybe through the UI or through the use of CI/CD scripts people can install themselves to keep things in sync.

Who's the target persona

We're targeting two kinds of people:

• The developers who want to define their services using the AsyncAPI specifications.
• Architects who want to gain some knowledge and put some kind of control over their EDAs.

In other words, we're targeting the so-called "providers" of the services and not so much the "consumers" of the services.

Why?

At the time of this writing, we're seeing an increased interest in using AsyncAPI to define and document EDAs. Most of the issues we hear about from users are those related to authoring AsyncAPI documents: how to properly structure it to map my service/API definition, how to properly reuse objects like servers, channels, and messages, etc.

I think the most important thing we can do right now is to help those interested in authoring AsyncAPI documents as much as possible, for two main reasons:

1. Developer experience: if the majority of our users are those who are writing AsyncAPI documents, we should help them.
2. Strategy: the more AsyncAPI files out there and the more quality the tools have, the better for us. People often stop using technologies that are not useful or are hard to use. Let's give our users one less reason to stop using AsyncAPI.

Proposed Changes

Note
We're working on the Studio project on Github: https://github.com/orgs/asyncapi/projects/16.
I'm just drafting a summary below for context in the meantime.

Summary

Layout improvement

The previous top bar disappears as it was useless (it only had the Studio logo and some links to stuff not related to Studio). Instead, it's now holding the name of the service (AsyncAPI file) we're developing and a few buttons to customize the layout. These are just the buttons that used to be on the sidebar, i.e., toggle Navigation, Docs, Diagnostics, etc.

But probably, the biggest change here is the introduction of this new sidebar on the left. It contains a bunch of buttons and also the avatar of the user. This new sidebar is meant to be the navigation for the whole application, meaning it's not just for the code editor as it was before. The purpose of this sidebar is to navigate to other parts of the application like Services, Governance, Settings, and more.

In general, now the layout is accommodated to start growing the application in a friendly and sane way.

Visual Designer

To address the first point of the vision ("Let people quickly start authoring AsyncAPI documents without having to learn the AsyncAPI syntax and nuances"), we're adding a visual designer. Essentially, this is just a UI to help you edit your AsyncAPI file. It takes the AsyncAPI document as input and outputs a new one with the changes you make on the UI. That's it. No more, no less.

Play with the interactive Figma prototype here: https://www.figma.com/proto/bPMB3lkMTOOMuKk0oGLuNm/Studio?type=design&node-id=96-2392&scaling=contain&page-id=0%3A1&starting-point-node-id=2%3A2.

Services Directory

This is the screen you land on when you're already signed in (once we implement signups, of course). It's a list of all the services (AsyncAPI documents) in your organization. They can be filtered down by tags (those in the AsyncAPI documents) and even search by words. You can also pin the services you work the most with on the top.

Play with the interactive Figma prototype here: https://www.figma.com/proto/bPMB3lkMTOOMuKk0oGLuNm/Studio?type=design&node-id=2-2&scaling=contain&page-id=0%3A1&starting-point-node-id=2%3A2.

What are these icons on the sidebar?

Top to bottom, these are: Services Directory (the one described above), Architecture Map, Registry, Governance, Teams management, Organization Settings, Add button (new Service, new Broker, new Message, etc.), Search, and User Menu (User settings, Logout, etc.

In the first iteration, we're only implementing the Layout Improvement and the Visual Designer but right after that, the first feature we'll target will be the Services Directory. There are no designs for the rest of the features yet but I'll try to briefly explain what they are about:

Architecture Map

It's pretty much something like this: https://app.eventcatalog.dev/visualiser/?type=all&name=AllEventsAndServices. I actually think that Studio should let you export to Event Catalog, either on the UI, the CLI, or both.

It's a map where you can see how things are connected. What services are sending what messages and what services are consuming them.

Registry

It's a registry/catalog of all the components of an AsyncAPI file: servers, channels, messages, schemas, parameters, server variables, etc. Everything that can be referenced using $ref has a place here. We should encourage and facilitate reusability as much as possible. Aside from the UI, there should be an API to address all these resources from a $ref. For instance, something like $ref: 'https://studio.asyncapi.com/api/org/1/servers/kafka-production'.

Governance

It's a place where architects can define Spectral rules that will be applied to all the AsyncAPI documents in an organization. This would help organizations enforce their own style guide.

Teams Management

It's a place where you can see, invite, and manage the members of an organization. Probably to be merged inside the next section.

Organization Settings

It's a place where you can tune the settings of your organization, e.g., the name, the members and their permissions, the teams, GitHub integration, etc.

Add Button

A quick way to create new stuff. A new service, a new server, a new message, a new schema, etc.

Search

Well, you know. Search anything and everything in your organizations :)

User Menu

The typical user menu where you can config your name, avatar, and other stuff. Also where the "Logout" menu item is.

Outcomes

See the Studio project on Github.

[Shurtu-gal]

Would love to work on it @fmvilas

[fmvilas]

You're already on my list mate :) Will hear from me soon 😄

[kaushik-rishi]

I've joined the Studio Visions Meeting.
I'm very much interested to contribute to the planned improvements. 🙂
All the suggested changes make sense. It would be a pretty hefty and amazing improvement providing an amazing UX to users of Studio. 🎉

Will we be having more such meetings around kickstarting the planning or everything from now will go on async ?
@fmvilas

[fmvilas]

Yay! 🎉 Yeah, we will be having them. @Amzani is currently organizing all the stuff around the project coordination. Everything will be transparent as always. No secret meetings or anything. We'll make sure you and others who are interested know about these meetings upfront, even to decide the best day and time :)

[Shurtu-gal]

Nice 😀

[princerajpoot20]

Excited about the Studio vision. 🚀
I'd love to contribute to this project. May I be a part of this? @fmvilas

[fmvilas]

Hey, @princerajpoot20! We would love to have you, of course! Please have a look at https://www.youtube.com/live/1jiRDmuA-zg?feature=share&t=671. In short, pick an issue from https://shapeit.app/projects/org/asyncapi/16 that no one has started yet (its progress is 0 and no one left a comment on the issue saying they're starting to work on it or is not assigned) and that's it. Leave a comment saying you're starting to work on it and make sure you give an update at least every 3 days. Ideally, update your progress (or no progress if you're stuck) every time you make some meaningful progress if the issue is taking longer to resolve.

Happy to help further if you need it. Either here or DM on Slack 👍

[princerajpoot20]

Sure, I'll check the issue list.

[rukundob451]

@fmvilas would surely love to be a part of this?

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[KhudaDad414]

Still relevant.

[Shahbaz898414]

Excited about the Studio vision. 🚀
I'd love to contribute to this project. May I be a part of this? @fmvilas