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

[magicmatatjahu]

As you know (or not) we didn't get to GSOC again this year, but we got a lot of submissions from potential contributors to our project proposals. One of them is An interface/project for describing errors/problems in tools in our organization.

Our organization has a lot of projects (and new ones are being added). One of the biggest problems with integrating a library to Studio/CLI/ServerAPI is that there is no structured way to deal with errors within libraries. In the ServerAPI as well as in the ParserJS we have tried to be a bit systematic and created an error system based on an interface called Problem. You can read more about it in below articles:

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

In general, the shape of the Problem is as follows (JSON Schema used):

    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type. When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: 'about:blank'
          example: 'https://api.asyncapi.com/problem/invalid-template-parameters'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable.
          example: Invalid AsyncAPI document.
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the problem.
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
      required:
        - type
        - title
      additionalProperties: true

As we can see, each error has its own type (identifier), which should be an url to the source where we describe the error/problem in detail. In addition, we have three other fields (including title, which is mandatory) to describe in more detail what is wrong in the given case of an error. Also, developer should be able to create additional properties - like in ParserJS the validationErrors etc.

Thanks to the use of given interface we will be able on the side of integration tools (ServerAPI/CLI/Studio) to see what problem we are dealing with and make appropriate logic. On the basis of the type we will know what additional fields the error has - in the case of normal errors this is difficult. For a CLI solution this will be an additional benefit, because we will be able to show the error in a friendly way in the console with a link to the error documentation.

For now, we have no idea if the errors/problems should be described in the repository of the project or if we should create some kind of global errors registry and display them under asyncapi.com/problem/{type}.

imabp is willing to contribute. I can mentor a particular project myself. The npm package itself would be called @asyncapi/problem. You can find more action points for this project in the issue: #266

@asyncapi/tsc_members please leave a vote here in this discussion if you are ok to accept the proposal of such a project. Feel free to also ask here a followup questions if needed

[fmvilas]

Yeah, I'm all for everything that means standardizing interfaces 👍

[derberg]

This is only for Nodejs projects, right?

This project does not exist, so you are basically asking for approval to actually create a new repository, right?

Can you explain why you think it is better to start from scratch under asyncapi org, rather than first work on proof of concept on a personal account like it was for example done with bundler or #223?

[magicmatatjahu]

This is only for Nodejs projects, right?

Yes.

It's just that bundler or even the new template was developed as a project that may not have made it into our organization's ecosystem. We can do it outside the organization on our profiles, but then hardly anyone will see the work and PRs that will be created. Is it worth it?

And you've had proof of concept for a long time here and here.

[derberg]

We can do it outside the organization on our profiles, but then hardly anyone will see the work and PRs that will be created

Just asking. To be honest, I personally would prefer to work on it under a personal profile and then donate, rather than face early all the "noise" related to repo setup, automation etc. Once it is started under a personal profile, @imabp can work on it at his own speed without pressure from the community.

And you've had proof of concept for a long time here and here.

I meant more PoC for the interface itself, not the idea. The idea makes total sense of course

[derberg]

@magicmatatjahu Repo is here https://github.com/asyncapi/problem with basic configuration. You and @imabp are invited as admins.
Push code when you are ready to do so. Add topics and update description too.

Lemme know once you are done. I will push GH Actions and setup branch protection.