website
website copied to clipboard
asyncapi
Integrate or re-implement APIs.guru asyncapi-directory
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
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.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
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.
Quick prototype: https://apitracker.io/specifications/asyncapi
What other data would be relevant to the list?
I think it would be great to also have a link to portal with documentation to see how companies render docs for users
Like https://docs.zoracloud.com/dev-mqtt-docs/latest/ or more what @MikeRalphson did with https://apis.guru/asyncapi-directory//html/[email protected]
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
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?
@derberg @Gdewilde I'd really love to work on this if granted the opportunity to do so
@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
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?
@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 https://github.com/asyncapi/website/issues/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/
@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.
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.
@AceTheCreator thanks for offering. Something that needs to be implemented by our company (Apideck). Will keep you posted!
@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?
@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?
@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 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.
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: https://github.com/slackapi/slack-api-specs/pull/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.
Added! Link to the API Tracker logo https://res.cloudinary.com/apideck/image/upload/v1621561371/apitracker/apitracker..svg
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.
This issue has been automatically marked as stale because it has not had recent activity :sleeping: 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 :heart: