An interface/project for describing errors/problems in tools in our organization.

[magicmatatjahu]

We have a lot of tools in our organization. Some of them have their own errror/problem trading system, some don't have it at all and only throw exceptions from the main function. I think we should standardize this.

In the ServerAPI as well as in the ParserJS we have a such of a system that we can extend and use in another repos.

We use in these repos the interface called Problem to describe all errors to not re-invent the wheel defining our "own error format".

Check out these posts for more context:

• Indicating Problems in HTTP APIs
• Understanding Problem JSON
• Succeeding in Failing - Darrel Miller

Implementations for that in ServerAPI and in ParserJS are a little different, so we should standarize it. In this task we have to do:

• think where we should have such a functionality, in the new repo or maybe in the existing one - important: we will use new library in separate projects so we cannot accept solution where we will duplicate the code
• write the Problem interface and helpers - we should discuss what helpers we need, but at least we need some function to create problem, retrieve type of problem, merge two or more problems to one etc
• write unit tests
• write docs how to use library and how to create new type of Problem
• create registry of all available problems inside organization - to discuss
• provide TS types, so I recommend to write new library in TS, not in pure JS
• replace existing solution in the ParserJS or in the ServerAPI (to choose) with new one
• create markdown "template" which will have structure to describe problems in the Readme of project (like https://github.com/asyncapi/parser-js#error-types)

Nice to have but not needed:

• integrate registry of problems in the ServerAPI - to discuss. As problem have type field we need to have page to describe details of the given type of problem. I think that https://api.server.com/problem/{type} will be good.

Existing implementation in the ServerAPI -https://github.com/asyncapi/server-api/blob/master/src/exceptions/problem.exception.ts
Existing implementation in the ParserJS - https://github.com/asyncapi/parser-js/blob/master/lib/errors/parser-error.js

[imabp]

This seems, like we need our own Error Management Interface 😄
What you think, of building a repo for our error management ?

[magicmatatjahu]

@imabp Yeah we need that because we have more and more integration and each library has another interface to describe errors, we should make them consistent.

What you think, of building a repo for our error management ?

I wrote about that in the first AP:

think where we should have such a functionality, in the new repo or maybe in the existing one - important: we will use new library in separate projects so we cannot accept solution where we will duplicate the code

but I think that separate repo will be better. Then we can treat it as library and fetch everywhere we want.

[imabp]

I think we should set up a new repo and try to have the initial setup which includes

• basic semantic release
• a dummy index export for now.

Choosing a name, is quite a bit difficult task.
So I have listed few names here.

• @asyncapi/error-interface
• @asyncapi/problem-interface
• @asyncapi/error-mgmt
• @asyncapi/error-management
• @asyncapi/error-management-interface

I feel to go with the error-management-interface or error-interface, but open to see, what you feel to :)

[magicmatatjahu]

@imabp We should go as you wrote, setup repo and needed things like semantic-release, however, please in mind that this task is participating in GSOC so we have to wait for it. As for the name I would prefer simple @asyncapi/problem :)

[imabp]

This is so cool...
I wanted to start it now itself. 😅..

Meanwhile I will create the proposal, which we can review on the way..

And then, during the gsoc period, we can start coding it out..

Hope that works @magicmatatjahu and you also agree... 😋

[magicmatatjahu]

Relax 😅 We'll write tomorrow on Slack about that :)

[BOLT04]

Amazing initiative @magicmatatjahu 💯 !!!!
I'm still curious about one thing, which is using the Problem details media type on all of AsyncAPI tools. We discussed that a bit here and on other PRs 🙂 .
If we do this approach in tools like the cli, the tool would have to know about HTTP status codes, etc.

Right now I'm thinking it doesn't really matter because the benefits of standardizing on an error format are greater in my opinion. It's a small dependency, and I don't think it's that big of a deal, even though a 500 error in a CLI is a bit weird 😅.

What does everyone else think?

[magicmatatjahu]

@BOLT04 Thanks!

Yes, we should discuss about type of problem. At the moment we use parser-js type in the parser-js repo, but in server-api the api.asyncapi.com/problem. We should standarize it. We can also create separate domain only for problems like problem.asyncapi.com/{type}.

About HTTP codes in the problem. I think that we should add httpStatusCode field to every problem that we can easily retrieve in the ServerAPI. It will not be difficult, but people will have to remember it and know which types are appropriate for which problems and this can be problematic.

[imabp]

@BOLT04 This package will add to more developer experience. So from that perspective, yes this package does add a lot of valu to existing tool chain.

[imabp]

@magicmatatjahu , let's keep the conversation going on this topic. I feel the need of it.
Do you have a specific call to action for now?

PS: I am reading more on the topics, previously shared in the first comment of this issue.

[magicmatatjahu]

@imabp Yeah, sure, please ask about anything and I will answer :)

Do you have a specific call to action for now?

What do you mean by call action? Do you mean use case(s) or what?

[imabp]

I meant callToAction, what should we do now ?
I am actually seeing and reading existing code...😅

[magicmatatjahu]

@imabp Hmm 🤔 As you know, we didn't get into GSOC so it's no problem for me to start doing it even now. Of course I can be your mentor, no problem. @derberg do we have to wait for something or can we start doing it (as part of our "internal GSOC")?

[imabp]

I have plans to start this from next week. As having exams this week.
Lets do it @magicmatatjahu .. Waiting for a green flag from @derberg

[magicmatatjahu]

@imabp Don't worry :) We can start even in next month. Good luck with exams!

[imabp]

Hello @magicmatatjahu
I am finally done with exams for now...
Shall we start with repo creation for this ?

[magicmatatjahu]

@imabp Sorry for that delay 😅 Yeah, I opt to create new repo, but I don't have full access in our Github organization, so @derberg could you create for us problem repository for @asyncapi/problem package? We'd be grateful ❤️

[derberg]

hey folks, I do have permissions to create repo, but I do not do it without TSC consent anymore.

I have to say I'm not 100% sure what is your goal. How about you present this subject on next community meeting, and then we can use this presentation as input for voting if we want to have such repo/project.

[magicmatatjahu]

We can do that :) I hope you'll wait @imabp, the meeting is next Tuesday. I think TSC will agree, it is a needed project.

[imabp]

Sure, we can wait for that time. :)

[magicmatatjahu]

@imabp Due to fact that you start working on that I recognize that you want to participate in our mentoring program with this project :) I'm assigning you to it, you don't have to worry about someone taking it.

[imabp]

Cool yes!! This sounds good to me.

[mcturco]

@magicmatatjahu do you think we could add a design contributor to work on this project if someone was interested? Just trying to gather more mentees to work on UI/UX projects. If so, can we add the "🎨 design" label to this issue?

[imabp]

Hey @mcturco not sure, if I can say one of my juniors who is into Visual Design, UI Design and UX Research.
Tagging him : @iipranavii

[mcturco]

@imabp Yes! If they are interested that would be great 😄

[iipranavii]

Thank you, @imabp, for the mention,
I would love to become a contributor for this project (and learn more from @mcturco :D)
I have experience in UX research and Visual design,
I worked with Abir on API hacks last year too, and am I Interning as a Product designer too, with most of my work in UI design and User research.
I would love to know more about it!

[mcturco]

That's great! Glad to have you here, @iipranavii. If you haven't already, I suggest joining our slack org and in the channel #12_design is where I post updates on the latest design happenings in the org.

Otherwise, if you and @imabp don't mind teaming up on this project, I think that would be awesome! Trying my best to fit the design process into open source, so I am also here if you need guidance.

[iipranavii]

Just joined the Slack workspace!
I would love to work with @imabp, we'll get in touch and team up on the project if he's interested too!
I have been trying to branch out into open source design, this will be a very good step in that direction!
Will be actively in touch with you ^_^

[magicmatatjahu]

@mcturco @iipranavii @imabp Don't want to ruin the dream, but that project has little to do with the UI. There won't be any additional UI here, we only have to think about the UX regarding the interface API.

[imabp]

yes, for this project, we dont think there is any specific UI requirement, as this will be hardly a package, @magicmatatjahu and me have created a task board here which you can see what all we have to do to complete this project.

.
For clearing out, I tagged @iipranavii because @mcturco was looking for more designers.

[iipranavii]

I understand, I will try to give my input wherever I can,
I think there are other issue like the Modelina Website which I can work on more extensively!

Thank you, @magicmatatjahu, for clearing it out!

[imabp]

@iipranavii please join #12_design in slack for more design issues to work on.

[mcturco]

Oops! Sorry for the misunderstanding, @imabp @magicmatatjahu. I think I saw the word "interface" in the title of this issue and automatically assumed that there would be UI involved. No problem! And thanks for clearing that up 😄

@iipranavii, yes, I encourage you to join in on some of the other issues tagged for the mentorship program that might require UI/UX. The Modelina website is a good choice!

[magicmatatjahu]

@imabp this idea was selected for AsyncAPI Mentorship 2022 -> #376 (comment)

Welcome to the mentorship program 🚀 I assumed you were still willing but let me know :)

[imabp]

Thank you so much @magicmatatjahu !!!!
I am already on this, so excited to collaborate with you, and ship this up!!

[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 ❤️

[magicmatatjahu]

Still valid.

[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 ❤️

[imabp]

valid

[magicmatatjahu]

@imabp I think we can close this one. We have created the problem repo and released the @asyncapi/problem package.

Repo: https://github.com/asyncapi/problem
NPM Package: https://www.npmjs.com/package/@asyncapi/problem