Integrate or re-implement APIs.guru asyncapi-directory

[MikeRalphson]

Reason/Context

• To demonstrate adoption of the specification
• To give users examples to work with
• To showcase use of the specification by member orgs etc
• In future, links to online code-generator, playground etc
• Current site location does not have eyeballs or traction

Description

• APIs.guru asyncapi-directory is currently a data-driven static site built with Eleventy, using around 4 template pages and the old static html generator
• Port or re-implement in next.js using scheduled GitHub actions to update the definitions from source
• Ignore streamdata stubs, as not maintained

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[Gdewilde]

As mentioned on Slack: https://asyncapi.slack.com/archives/C34F2JV0U/p1615954697001600

Apideck will fast-track the apitracker.io overview, so it’s easier to compare. We can also make an effort to integrate the data into the asyncapi.io website as soon as it’s done https://apitracker.io/specifications.

[Gdewilde]

Quick prototype: https://apitracker.io/specifications/asyncapi

What other data would be relevant to the list?

[derberg]

I think it would be great to also have a link to portal with documentation to see how companies render docs for users

[Gdewilde]

Like https://docs.zoracloud.com/dev-mqtt-docs/latest/ or more what @MikeRalphson did with https://apis.guru/asyncapi-directory//html/[email protected]

[derberg]

I think best is to link to the official ones, then people can see different use cases on how EDA docs are presented to users

the playground is already rendering docs using the official latest HTML template, so no need to add something separate I think

[derberg]

a dedicated view where we could have a list of specs pulled from apitracker is under Community navigation item, a new view like In Production or something like this?

[Gdewilde]

Sounds good!

[AceTheCreator]

@derberg @Gdewilde I'd really love to work on this if granted the opportunity to do so

[derberg]

@Gdewilde what do you think? would you need some help with integration?

btw I guess we still need to figure out how people can report manually their documents to get them pulled on the list

[Gdewilde]

Sure, we first need to get the API in place at the API Tracker.

btw I guess we still need to figure out how people can report manually their documents to get them pulled on the list

--> Indeed, I was thinking along the lines of http://apisjson.org/ that they put at the root of their website/dev docs or in a GitHub repo they manage. We don't want to make this an opaque process. @MikeRalphson, what's your experience from running the OpenAPI directory?

Do you have any ideas?

[derberg]

@AceTheCreator it can take some time until you could actually start working on this one. I suggest finding some other issue. If you want to do some frontend then from this repo I recommend #212 + we also have a react component for the spec where some help would be highly appreciated as more and more users use the component https://github.com/asyncapi/asyncapi-react/

[AceTheCreator]

@derberg That's fine and I'll definitely check out other issues from the link mentioned above. I'll also try to keep in touch with this issue just in case if I could be of help.

[MikeRalphson]

I was thinking along the lines of http://apisjson.org/ that they put at the root of their website/dev docs or in a GitHub repo they manage. We don't want to make this an opaque process. @MikeRalphson, what's your experience from running the OpenAPI directory?

We use a mix of research, spidering, scraping and user-submissions via a form which creates GitHub issues. The schema.org WebAPI type can be used to declare that a web-page describes a Web API (of any type) using JSON-LD or RDF.

[derberg]

@Gdewilde hey, how is it going? any progress on the API side?

[Gdewilde]

Hi @derberg! I hope to get to it this weekend.

[AceTheCreator]

@Gdewilde How can I be of help?

[Gdewilde]

@AceTheCreator thanks for offering. Something that needs to be implemented by our company (Apideck). Will keep you posted!

[Gdewilde]

@AceTheCreator @derberg the API powering https://www.apitracker.io/specifications/asyncapi is now available at https://www.apitracker.io/api/specifications/asyncapi Still need to write a spec for it tho 😅 Are you able to get started?

[Gdewilde]

@derberg can you verify if we labeled the protocols correctly?

[AceTheCreator]

@AceTheCreator @derberg the API powering https://www.apitracker.io/specifications/asyncapi is now available at https://www.apitracker.io/api/specifications/asyncapi Still need to write a spec for it tho Are you able to get started?

Looks good and great job @Gdewilde. @derberg what do you think?

[derberg]

@Gdewilde looks awesome 🎉 My only concern is if Gitter and Slack should be there as they are 1.2 and not 2.0 AsyncAPI and I'm afraid that would promote old versions this way 🤔 but it is nice to see Slack on the list on the other hands 😕

the other one we can add is eBay https://developer.ebay.com/marketplace-account-deletion as they wrote about AsyncAPI adoption recently https://tech.ebayinc.com/engineering/asyncapi-2-0-enabling-the-event-driven-world/

Also we could add this https://github.com/asyncapi/spec/blob/master/examples/2.0.0/websocket-gemini.yml and mark AsyncAPI as author. It is a spec file I created for Gemini's official API https://docs.sandbox.gemini.com/websocket-api/#market-data

So we would take 2 off the list that are for old spec, and add 2 new from cool projects. Bilans = 0 😄

@AceTheCreator yup, now we need to think how to present it in the UI. If we need a separate view, or rather have it on the landing page. @fmvilas as you are so far our official website designer, we need your input

@Gdewilde please share us the API Tracker logo that we could put in our website, under the list of API, as a "thank you" reference that the list is powered by API Tracker. This is how we can give back for the effords

[AceTheCreator]

@AceTheCreator yup, now we need to think how to present it in the UI. If we need a separate view, or rather have it on the landing page. @fmvilas as you are so far our official website designer, we need your input

@derberg I think it will be cool to have it on a separate view and maybe have something that references it on the landing page. Well, let see what approach @fmvilas thinks.

[fmvilas]

My only concern is if Gitter and Slack should be there as they are 1.2 and not 2.0 AsyncAPI and I'm afraid that would promote old versions this way

In case it helps, I contributed a migration to v2 on the Slack API: slackapi/slack-api-specs#37. Seems it not going to be merged because they plan to generate it from their code but it's a good start. Regarding Gitter, we can convert it to v2 very easily. Just copy the document and paste it on the Playground. It will transform it automatically.

@fmvilas as you are so far our official website designer, we need your input

Let's work on this together.

[Gdewilde]

Ok, we will index the eBay and Gemini specs shortly!

[Gdewilde]

Added! Link to the API Tracker logo https://res.cloudinary.com/apideck/image/upload/v1621561371/apitracker/apitracker..svg

[derberg]

Let's work on this together.

@fmvilas @AceTheCreator I think it would be good to have a short, max 3-5 elements list displayed on the landing page under some new section like AsyncAPI in the wild and a link to click for more that would take you to separate view of all specs. Also there would be a new element in the navigation, under Learning called something like Real life examples

The view with all the specs would be super similar to what is currently on API Tracker, and below or above the list we could have a "thank you reference" to API Tracker + clear information how easily you can add your APIs to the list.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[AceTheCreator]

@derberg @fmvilas can we start implementing this?

[derberg]

I think so, @Gdewilde the API is ready right?

[Gdewilde]

Yes, https://apitracker.io/api/specifications/asyncapi

[AceTheCreator]

@derberg @fmvilas Should I come up with some design implementation?

[derberg]

@AceTheCreator would be awesome. I cannot help much here, but API Tracker set a good direction here

most important is where, where we will render it, as I initially thought about main landing page, but am not so sure about it any more. Maybe that should be Use Cases view that we did not implement yet and still waiting for first use case

[AceTheCreator]

@derberg what do you mean by first use case?

[derberg]

oh yeah, sorry, so we have this on the website

Use cases are not ready, but we could already have a landing page there, once you click Use cases. And landing page would say, no detailed use cases available yet, contact us to give yours and another explanation that you can see below a list of real world usage of AsyncAPI files and a list of data provided by API Tracker.

Makes sense?

[AceTheCreator]

@derberg That definitely makes sense. I'll come up with something and share with you guys

[AceTheCreator]

@mcturco I would really love and appreciate it if you could help develop some design for this issue. and probably use https://www.apitracker.io/specifications as a reference to what we're trying to achieve. Or @derberg what do you think? Don't blame me for being suck at design 🙂

[mcturco]

Hi @AceTheCreator! Saw your comment last week but just now finished reading through the history of this issue. I would love to help out with this! Just to confirm that I understand the goals:

• We basically want to render this chart: https://www.apitracker.io/specifications/asyncapi on a new page on the website matching the AsyncAPI style & have powered by [apitracker logo] near it
• Then, we want to add a call to action on the home page to view the chart of specs on the above new landing page

Let me know if that is accurate and I can get started on a design mock up!

[AceTheCreator]

@mcturco you're absolutely correct!

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

[Leamsi9]

May I suggest an iterative process, given it's been a while since this got going and I suspect the lack of motion is to do with what's required vs what's available human resource wise?

My suggestion is we have two separate section:
Who Uses AsyncApi which could go in the community section and is a simple list of every company we know uses AsyncApi; and a Case Studies section, where we dive into use cases we want to amplify and learn from.

I suggest we could iterate along the lines of the @MikeRalphson's approach:

We use a mix of research, spidering, scraping and user-submissions via a form which creates GitHub issues. The schema.org WebAPI type can be used to declare that a web-page describes a Web API (of any type) using JSON-LD or RDF.

I propose

1. a simple research based list to start with
2. then/in parallel a user submission form that creates git issues in the repo updating the directory
3. then/in parallel, we could work on case studies from our existing list to add to the case study section
4. then we can add a dynamic stream from API tracker (and others) that checks against our list and adds anything missing
5. We could move on to some spidering to supplement the cases.

I would be happy to volunteer for 1+2 with @AceTheCreator for now, and @AceTheCreator has offered to get started with 3 (he could create first drafts to a template, and code review could tweak and finalise them.

That might generate enough momentum to move to 4+5?

If this sounds good, one question would be what format we want the list to be in. Not sure what we use in the back end, and whether the list would go into a database, or live as json or even as Markdown in the repo for v.0.

[AceTheCreator]

May I suggest an iterative process, given it's been a while since this got going and I suspect the lack of motion is to do with what's required vs what's available human resource wise?

My suggestion is we have two separate section: Who Uses AsyncApi which could go in the community section and is a simple list of every company we know uses AsyncApi; and a Case Studies section, where we dive into use cases we want to amplify and learn from.

I suggest we could iterate along the lines of the @MikeRalphson's approach:

We use a mix of research, spidering, scraping and user-submissions via a form which creates GitHub issues. The schema.org WebAPI type can be used to declare that a web-page describes a Web API (of any type) using JSON-LD or RDF.

I propose

1. a simple research based list to start with
2. then/in parallel a user submission form that creates git issues in the repo updating the directory
3. then/in parallel, we could work on case studies from our existing list to add to the case study section
4. then we can add a dynamic stream from API tracker (and others) that checks against our list and adds anything missing
5. We could move on to some spidering to supplement the cases.

I would be happy to volunteer for 1+2 with @AceTheCreator for now, and @AceTheCreator has offered to get started with 3 (he could create first drafts to a template, and code review could tweak and finalise them.

That might generate enough momentum to move to 4+5?

If this sounds good, one question would be what format we want the list to be in. Not sure what we use in the back end, and whether the list would go into a database, or live as json or even as Markdown in the repo for v.0.

@Leamsi9 going into a database is not an option in my opinion, but we should definitely decide between JSON/Markdown 😀

[derberg]

@Leamsi9 @AceTheCreator in regards to use cases and case studies, this should be interesting for you:

• https://github.com/orgs/asyncapi/discussions/187
• feat: case studies content setup #921

[AceTheCreator]

Yes, https://apitracker.io/api/specifications/asyncapi

@Gdewilde I noticed this endpoint is not working. Any idea why?

[Gdewilde]

Thanks for the heads-up. We fixed it!

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

[akshatnema]

Closing this issue since no further updates from the participants.