docs: small social media system example

examples/social-media/backend.asyncapi.yaml

@@ -0,0 +1,46 @@
+asyncapi: 2.2.0
+
+info:
+  title: Website Backend
+  version: 1.0.0
+
+servers:
+  websiteWebSocketServer:
+    url: ws://mycompany.com/ws
+    protocol: ws
+  mosquitto:
+    url: mqtt://test.mosquitto.org
+    protocol: mqtt
+    bindings:
+      mqtt:
+        clientId: websocketServer
+
+channels:
+  comment/liked:
+    description: Notify all the services that a comment has been liked.
+    servers: ['mosquitto']
+    subscribe: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/commentLiked'
+  like/comment:
+    description: When a comment like is received from the frontend.
+    servers: ['websiteWebSocketServer']
+    publish: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/likeComment'
+  comment/{commentId}/changed:
+    description: When an event from the broker arrives telling us to update the comment likes count on the frontend.
+    parameters: 
+      commentId:
+        schema: 
+          $ref: './dictionary.asyncapi.yaml#/components/schemas/commentId'
+    servers: ['mosquitto']
+    publish: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/commentChanged'
+  update/comment/likes:
+    description: Update comment likes count in the frontend.
+    servers: ['websiteWebSocketServer']
+    subscribe: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/updateCommentLikes'

examples/social-media/comments-service.asyncapi.yaml

@@ -0,0 +1,31 @@
+asyncapi: 2.2.0
+
+info:
+  title: Comments Service
+  version: 1.0.0
+  description: This service is in charge of processing all the events related to comments.
+
+servers:
+  mosquitto:
+    url: mqtt://test.mosquitto.org
+    protocol: mqtt
+    bindings:
+      mqtt:
+        clientId: comment-service
+
+channels:
+  comment/liked:
+    description: Updates the likes count in the database and sends the new count to the broker.
+    publish: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/commentLiked'
+  comment/{commentId}/changed:
+    description: Sends the new count to the broker after it has been updated in the database.
+    parameters: 
+      commentId:
+        schema: 
+          $ref: './dictionary.asyncapi.yaml#/components/schemas/commentId'
+    subscribe: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/commentChanged'
+

examples/social-media/dictionary.asyncapi.yaml

@@ -0,0 +1,60 @@
+asyncapi: 2.2.0
+
+info:
+  title: Dictionary for organization-wide definitions
+  version: 1.0.0
+
+components:
+  messages:
+    commentLiked: 
+      payload: 
+        $ref: '#/components/schemas/commentLikedPayload'
+    likeComment: 
+      payload: 
+        $ref: '#/components/schemas/likeCommentPayload'
+    commentChanged: 
+      payload: 
+        $ref: '#/components/schemas/commentChangedPayload'
+    updateCommentLikes: 
+      payload: 
+        $ref: '#/components/schemas/updateCommentLikesPayload'
+
+  schemas: 
+    commentLikedPayload: 
+      type: object
+      title: commentLikedPayload
+      additionalProperties: false
+      properties:
+        commentId: 
+          allOf: 
+            - $ref: '#/components/schemas/commentId'
+            - description: Id of the comment that was liked
+    likeCommentPayload: 
+      type: object
+      title: likeCommentPayload
+      additionalProperties: false
+      properties:
+        commentId: 
+          allOf: 
+            - $ref: '#/components/schemas/commentId'
+            - description: Id of the comment that should be liked
+    commentChangedPayload: 
+      type: object
+      title: commentChangedPayload
+      additionalProperties: false
+      properties:
+        commentId: 
+          allOf: 
+            - $ref: '#/components/schemas/commentId'
+            - description: Id of the comment that was changed, such as when someone liked it.
+    updateCommentLikesPayload:
+      type: object
+      title: updateCommentLikesPayload
+      additionalProperties: false
+      properties:
+        commentId: 
+          allOf: 
+            - $ref: '#/components/schemas/commentId'
+            - description: Id of the comment that was changed, such as when someone liked it.
+    commentId:
+      type: string

examples/social-media/frontend.asyncapi.yaml

@@ -0,0 +1,22 @@
+asyncapi: 2.2.0
+
+info:
+  title: Website WebSocket Client
+  version: 1.0.0
+
+servers:
+  websiteWebSocketServer:
+    url: ws://mycompany.com/ws
+    protocol: ws
+
+channels:
+  like/comment:
+    description: Notify the backend that a comment has been liked.
+    subscribe: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/likeComment'
+  update/comment/likes:
+    description: Update the UI when the comment likes count is updated.
+    publish: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/updateCommentLikes'

examples/social-media/notification-service.asyncapi.yaml

@@ -0,0 +1,20 @@
+asyncapi: 2.2.0
+
+info:
+  title: Notifications Service
+  version: 1.0.0
+
+servers:
+  mosquitto:
+    url: mqtt://test.mosquitto.org
+    protocol: mqtt
+    bindings:
+      mqtt:
+        clientId: notification-service
+
+channels:
+  comment/liked:
+    description: When a "comment has been liked" message is received, it sends an SMS or push notification to the author.
+    publish: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/commentLiked'

examples/social-media/public.asyncapi.yaml

@@ -0,0 +1,21 @@
+asyncapi: 2.2.0
+
+info:
+  title: Public API 
+  description: Public API for others to interact with the system
+  version: 1.0.0
+
+servers:
+  mosquitto:
+    url: mqtt://test.mosquitto.org
+    protocol: mqtt
+    bindings:
+      mqtt:
+        clientId: public-api
+
+channels:
+  comment/liked:
+    description: When a "comment has been liked" message is received, it sends an SMS or push notification to the author.
+    publish: 
+      message:
+        $ref: './dictionary.asyncapi.yaml#/components/messages/commentLiked'

examples/social-media/readme.md

@@ -0,0 +1,19 @@
+## Small social media example
+
+Say we have a social network, a very basic one, where all you can do is upvoting comments.
+
+The individual services that need to be defined are:
+
+- A frontend application where users interact through the website, where they can like comments.
+- A backend WebSocket server that sends and receives events for the UI to update in real-time.
+- A comment service which processes all events related to comments through a message broker.
+- A public-facing API which allows others to get notified about updates.
+
+[![](https://mermaid.ink/img/eyJjb2RlIjoiXG5ncmFwaCBURFxuIHNlcnZlcjFbKHdzOi8vbXljb21wYW55LmNvbS93cyldXG5XZWJzaXRlQmFja2VuZFtXZWJzaXRlIEJhY2tlbmRdXG5XZWJzaXRlV2ViU29ja2V0Q2xpZW50W1dlYnNpdGUgV2ViU29ja2V0IENsaWVudF1cbldlYnNpdGVXZWJTb2NrZXRDbGllbnQgLS0gbGlrZS9jb21tZW50IC0tPiBzZXJ2ZXIxXG5zZXJ2ZXIxIC0tIGxpa2UvY29tbWVudCAtLT4gV2Vic2l0ZUJhY2tlbmRcbldlYnNpdGVCYWNrZW5kIC0tIHVwZGF0ZS9jb21tZW50L2xpa2VzIC0tPiBzZXJ2ZXIxXG5zZXJ2ZXIxIC0tIHVwZGF0ZS9jb21tZW50L2xpa2VzIC0tPiBXZWJzaXRlV2ViU29ja2V0Q2xpZW50XG5zZXJ2ZXIyWyhtcXR0Oi8vdGVzdC5tb3NxdWl0dG8ub3JnKV1cbldlYnNpdGVCYWNrZW5kIC0tIGNvbW1lbnQvbGlrZWQgLS0-IHNlcnZlcjJcbkNvbW1lbnRzU2VydmljZVtDb21tZW50cyBTZXJ2aWNlXVxuc2VydmVyMiAtLSBjb21tZW50L2xpa2VkIC0tPiBDb21tZW50c1NlcnZpY2Vcbk5vdGlmaWNhdGlvbnNTZXJ2aWNlW05vdGlmaWNhdGlvbnMgU2VydmljZV1cbnNlcnZlcjIgLS0gY29tbWVudC9saWtlZCAtLT4gTm90aWZpY2F0aW9uc1NlcnZpY2VcbkNvbW1lbnRzU2VydmljZSAtLSBcImNvbW1lbnQve2NvbW1lbnRJZH0vY2hhbmdlZFwiIC0tPiBzZXJ2ZXIyXG5zZXJ2ZXIyIC0tIFwiY29tbWVudC97Y29tbWVudElkfS9jaGFuZ2VkXCIgLS0-IFdlYnNpdGVCYWNrZW5kXG5QdWJsaWNBUElbUHVibGljIEFQSV1cbnNlcnZlcjIgLS0gXCJjb21tZW50L2xpa2VkXCIgLS0-IFB1YmxpY0FQSSIsIm1lcm1haWQiOnsidGhlbWUiOiJkYXJrIn0sInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjpmYWxzZX0)](https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiXG5ncmFwaCBURFxuIHNlcnZlcjFbKHdzOi8vbXljb21wYW55LmNvbS93cyldXG5XZWJzaXRlQmFja2VuZFtXZWJzaXRlIEJhY2tlbmRdXG5XZWJzaXRlV2ViU29ja2V0Q2xpZW50W1dlYnNpdGUgV2ViU29ja2V0IENsaWVudF1cbldlYnNpdGVXZWJTb2NrZXRDbGllbnQgLS0gbGlrZS9jb21tZW50IC0tPiBzZXJ2ZXIxXG5zZXJ2ZXIxIC0tIGxpa2UvY29tbWVudCAtLT4gV2Vic2l0ZUJhY2tlbmRcbldlYnNpdGVCYWNrZW5kIC0tIHVwZGF0ZS9jb21tZW50L2xpa2VzIC0tPiBzZXJ2ZXIxXG5zZXJ2ZXIxIC0tIHVwZGF0ZS9jb21tZW50L2xpa2VzIC0tPiBXZWJzaXRlV2ViU29ja2V0Q2xpZW50XG5zZXJ2ZXIyWyhtcXR0Oi8vdGVzdC5tb3NxdWl0dG8ub3JnKV1cbldlYnNpdGVCYWNrZW5kIC0tIGNvbW1lbnQvbGlrZWQgLS0-IHNlcnZlcjJcbkNvbW1lbnRzU2VydmljZVtDb21tZW50cyBTZXJ2aWNlXVxuc2VydmVyMiAtLSBjb21tZW50L2xpa2VkIC0tPiBDb21tZW50c1NlcnZpY2Vcbk5vdGlmaWNhdGlvbnNTZXJ2aWNlW05vdGlmaWNhdGlvbnMgU2VydmljZV1cbnNlcnZlcjIgLS0gY29tbWVudC9saWtlZCAtLT4gTm90aWZpY2F0aW9uc1NlcnZpY2VcbkNvbW1lbnRzU2VydmljZSAtLSBcImNvbW1lbnQve2NvbW1lbnRJZH0vY2hhbmdlZFwiIC0tPiBzZXJ2ZXIyXG5zZXJ2ZXIyIC0tIFwiY29tbWVudC97Y29tbWVudElkfS9jaGFuZ2VkXCIgLS0-IFdlYnNpdGVCYWNrZW5kXG5QdWJsaWNBUElbUHVibGljIEFQSV1cbnNlcnZlcjIgLS0gXCJjb21tZW50L2xpa2VkXCIgLS0-IFB1YmxpY0FQSSIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkYXJrXCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6ZmFsc2V9)
+
+This ensures that we try to describe the following use-cases mixed together:
+
+- A public API
+- A WebSocket server and client
+- A broker setup
+