Async API Integration

[JoeHillyard]

Recently I have noticed a lot of progression with the Async API Specification and the community behind it - while OAS is a well matured staple, there is a lot of momentum towards event-driven architecture & message based solutions including WebSockets, Kafka and other message brokers.

My motivation behind this would be to have a unified API across multiple protocols that can be fronted with an aggregated view (Just an example - that repo is a bit dated)

I'm interested to hear your thoughts on the matter and whether its a viable implementation etc.

Thanks!

[Romakita]

AsyncApi seems to be an evolution of OpenSpec. It could be interesting to support it but I don’t know what is the cost and the effort to support it.

actually, Ts.ED generate directly a oas and jsonschema. If the asyncApi is an extension of oas, it could really easy to integrate it.

[Romakita]

After investigation, AsyncAPI seems to be more complex to integrate.
Based on this link:
https://support.smartbear.com/swaggerhub/docs/asyncapi-support.html

Converting AsyncAPI

It's not possible to convert between OpenAPI and AsyncAPI, as they're designed to describe different systems. It is possible to describe HTTP interactions with AsyncAPI but not recommended for describing full servers and clients.

But create a module to transform metadata to AsyncAPI could be possible. @tsed/schema maybe need some modification to allow a module to add his own transformation definition. I'll try to make that possible in the first time.

@JoeHillyard If you are interested, can write in this discussion the different usecase. For example, "as developer If I write a controller with some method, it should produce the following AsyncAPI schema."

Describing acceptance criteria and usecase will help us to see what is the complexity to achieve the new @tsed/asyncapi module :D

See you

[joe-hillyard]

Thanks for getting back to me and keeping the thread alive!

In my opinion AsyncAPI did a good of trying to maintain a level of parity with OAS, a quick overiew of the schema mapping shows while there are fundamental differences they are not too dissimilar.

I would imagine this would require a new type of controller as to not clash or force two different paradigms together, please find a first draft of some psuedo below:

@EventController($channelName) // channel = user/signedup
class AccountRegistrationController() {
  @EventPublish(($message , {eventData}){ // operation = publish, message = userSignedUp, eventData = {eventMeta} 
  async userSignedUp(){
    // implement here
  }
}

@EventController($channelName) // channel = user/signedup
class EmailController() {
  @EventSubscribe(($message , {eventData}){  // operation = subscribe, message = UserSignedUp, eventData = {eventMeta} 
  async sendSignUpEmail(@EventPayload data){
    // implement here
  }
}

asyncapi: 2.0.0
info:
  title: Example
  version: '1.0.0'
  description: |
    Manages user accounts registration.

servers:
  production:
    url: ws://tsed.io
    protocol: ws
    description: Test WS Socket

channels:
  user/signedup:
    publish:
      operationId: produceUserSignUpEvent
      message:
        $ref: '#/components/messages/UserSignedUp'
    subscribe:
      operationId: consumeUserSignUpEvent
      message:
        $ref: '#/components/messages/UserSignedUp'

components:
  messages:
    UserSignedUp:
      name: userSignedUp
      title: User signed up event
      summary: Inform about a new user registration
      contentType: application/json
      payload:
        $ref: '#/components/schemas/userSignedUpPayload'

  schemas:
    userSignedUpPayload:
      type: object
      properties:
        firstName:
          type: string
          description: "foo"
        lastName:
          type: string
          description: "bar"
        email:
          type: string
          format: email
          description: "baz"
          createdAt:
            type: string
            format: date-time

This is just a first draft - I will come back to review with fresh eyes later :)

Thanks again!

[Romakita]

It seems to be more indicated to be used with socket io ?

[joe-hillyard]

It can be HTTP, Websockets, Kafka, MQTT - at its core it's an event-based paradigm whereas REST is not. So I imagine WS may be the de facto protocol where REST uses HTTP, but both could utilize both.

[Romakita]

Ok :)
I'm just thinking of rewriting the @tsed/socketio module
but it would also be a good use case to develop the @tsed/websocket module while generating AsyncAPI

and therefore ensure that @tsed/schema embeds the maximum decorator to describe the interactions (Subscribe, Event etc...).

My question is about HTTP protocol. How we can reflect the Verb method in AsyncAPI.
From what I've seen it's not something reflected in the AsyncAPI doc. I have the impression in this approach, we will mainly do POST messages to enter the Event driven architecture. in this case, a simple annotation @Publish / @Subscribe will be enough to display the method in AsyncAPI.

@Controller("/path")
export class MyController {
   @Post('/:id')
   @Publish()  // will be displayed as publish operation in AsyncAPI 
   @Returns(200, Array).Of(Model).ContentType('application/json')
   postSomething(@BodyParams() payload: PayloadModel) {
   }
   
   @Get("/:id") // not displayed in AsyncAPI
   otherMethod() {
   }
}

asyncapi: 2.0.0
info:
  title: Example
  version: '1.0.0'
  description: |
    Manages user accounts registration.

servers:
  production:
    url: https://tsed.io
    protocol: https
    description: HTTP test
    
channels:
  /path/:id:
    publish:
      operationId: myController_postSomething
      message:
        $ref: '#/components/messages/MyModel'
schemas:   
   MyModel: 
       type: object

In this case, it could be easy to display some endpoints by using the appropriate decorators. But Maybe I'm wrong to try to mix a Rest API and Async API.

[Romakita]

Hello @JoeHillyard

After a long moment to learn and understand correctly the Async API spec, I'm happy to said you, I'm working on a future implementation.

You can see the draft PR:
#2441

The @tsed/schema generate a async API spec but I chosen to not generate the http endpoint and stay focused on the WebSocket (aka socket.io).

The base is here, it should support multiple channels (aka multiple socket.io rooms).

The next step is to work on the new @tsed/socketio-v2 package.

Unlike the old package which generated its own metadata, the new package will take over the entire architecture of the metadata collected via @tsed/schema.

The goal is to be able to declare both a Rest controller and a Websocket controller as follows:

class PetCategory {
  @Required()
  @Groups("!partial", "!create", "!update")
  id: string;

  @Required()
  @Example("doggie")
  name: string;
}

enum PetStatus {
  AVAILABLE = "available",
  PENDING = "pending",
  SOLD = "sold"
}

class Pet {
  @Required()
  @Groups("!partial", "!create", "!update")
  id: string;

  @Required()
  @Example("doggie")
  name: string;

  @Property()
  category: PetCategory;

  @CollectionOf(String)
  tags: string[];

  @Enum(PetStatus)
  status: PetStatus;
}

@Controller("/")
@Name("PetStore")
class PetController {
  @Use("/")
  middleware(@PathParams("id") id: string) {}

  @Get("/:id")
  @Publish("pet.get")
  @Subscribe("pet.get")
  @Returns(200, Pet).Description("Returns a pet")
  @Returns(404)
  get(@PathParams("id") id: string) {
    return null;
  }

  @Get("/")
  @Publish("pet.getAll")
  @Subscribe("pet.getAll")
  @Returns(200, Array).Of(Pet).Description("Returns all pets")
  getAll() {
    return [];
  }

  @Patch("/:id")
  @Publish("pet.patch")
  @Subscribe("pet.updated")
  @Returns(200, Pet).Description("Returns a pet")
  @Returns(404)
  @Description("Patch a pet")
  patch(@PathParams("id") id: string, @BodyParams() @Partial() partial: Pet) {
    return null;
  }

  @Post("/:id")
  @Publish("pet.update")
  @Subscribe("pet.created")
  @Returns(200, Pet).Description("Returns a pet")
  @Returns(404)
  @Description("Update a pet")
  post(@BodyParams() @Groups("update") pet: Pet) {
    return null;
  }

  @Put("/")
  @Publish("pet.create")
  @Subscribe("pet.updated")
  @Returns(201, Pet)
  @Returns(404)
  @Description("Create a pet")
  put(@BodyParams() @Groups("create") pet: Pet) {
    return null;
  }

  @Delete("/:id")
  @Publish("pet.delete")
  @Subscribe("pet.deleted")
  @Returns(204)
  @Returns(404)
  @Description("Delete a pet")
  delete(@PathParams("id") id: string) {
    return null;
  }
}

it's a huge challenge but I'm sure that this way of doing things will be a real success with the devs when they want to exploit the code from a Rest controller to the websocket.

But that doesn't mean that we can't make a dedicated WS controller to have more flexibility.

I also plan to support the async hook (@tsed/di) and therefore the @Context() and @InjectContext() decorators to maximize code compatibility with Platform API.

In other words, an injectable Service developed for a Web server, for the CLI or for SocketIO should be able to function in the same way as long as the code does not call on instructions specific to each environment.

I hope this news will enjoy you!
See you
romain