vs-asyncapi-preview VS spec

Regular maintenance for our VS Code plugin.

Onboarding - Enable developers to quickly learn how to consume the exposed APIs. For example, offer OpenAPI or AsyncAPI documentation and provide a portal and sandbox.

https://ballerina.io/ and https://www.asyncapi.com/ seem like two efforts to move in this direction a bit for web APIs.

I'm in the process of migrating PrintNanny.ai's remote command/event system off Cloud IoT Core. I've been running on IoT Core for 1.5 years. Here's my breakdown of the costs...

- $236.99 in usage, approx 1% of project's total revenue

- ~20 hours to implement pub/sub applications running on a mix of Raspberry Pi & GCP VMs. Implementations were in Rust and Python. It would have taken much, much longer to stand up a managed MQTT broker and identity/key management that I felt comfortable using in my own home, let alone providing to customers.

- Hundreds of hours implementing and debugging glue between GCP's Pub/Sub product, websocket-based subscribers, and MQTT subscribers/publishers.

I don't regret my decision (wouldn't have shipped otherwise), but I'm looking forward to the next phase. Here's what I'm migrating towards:

- NATs message broker. NATS supports connections via MQTT and Websocket protocols, besides NATS own protocol.

- django-nats-nkeys for org, identity, and JWT management (not production-ready, don't use this until I've been eating my own dog food for a few months) [1]

- AsyncAPI schemas [2] for core message APIs, including schemas for 3rd-party printer software events (OctoPrint, Moonraker, Repetier, etc). This will underpin PrintNanny's plugin system.

[1] https://github.com/bitsy-ai/django-nats-nkeys

[2] https://www.asyncapi.com/

A contract is nothing but a regular piece of code. So, you cannot apply the contract written in Java in the microservices created with Golang. If you need to use varying technologies and languages for the different parts of your system, then implementing statically typed contracts might become a challenge. There are some solutions on the market. For example, OpenAPI and AsyncAPI specifications can generate code snippets based on the provided configurations. Anyway, the approaches have limitations.

There is also great stuff going on around AsyncAPI

The framework is driven by the AsyncAPI specification, built on top of Flask-SocketIO. and inspired by Connexion.

Gabriel Gore, Sachin Muralidhara, and Sean McGovern taught us a little more about AsyncAPI , an open-source specification for event-driven architectures (EDA). It defines interfaces for Async APIs, similar to what OpenAPI or Swagger does for RESTful services. You can automate and formalize docs, you can generate code, you can validate schemas for event-driven microservices, and it's compatible with OpenAPI for a lot of use cases. (If you have an existing code base with Open API schemas in it, you may be able to port those over to AsyncAPI; here’s a nifty comparison chart.)

Protobuf is one of the ways to implement Messaging Contracts there are more options like Pact, AsyncApi

Gitter-streaming API

Here comes AsyncAPI: built with OpenAPI’s legacy in mind and sharing some concepts with, it uses some parts of its original structure and optimizes them for asynchronous needs.