A Streaming AsyncAPI Example For The Gitter API

We profiled an AsyncAPI Definition For The Slack Real Time Messaging API last week, showing what is possible for profiling Websocket APIs using the machine-readable specification format. This week we wanted to showcase a slight variation by profiling an API that employs Server-Sent Events (SSE), and takes advantage of the streaming object for the AsyncAPI specification. Reusing many of the elements are similar for defining a Websocket API, but putting the stream object to work, instead of events or topics as you might for other event or message-driven APIs. This is a streaming API for the message and networking platform Gitter, which provides an SSE version of their API for listening to messages, events, and changes in rooms. The Gitter Streaming API is much simpler than the Slack Real-Time Message API was, but still provides a nice glimpse at how to use AsyncAPI for SSE streams as opposed to Websockets:

asyncapi: '1.2.0'
info:
  title: Gitter Streaming API
  version: '1.0.0'

servers:
  - url: https://stream.gitter.im/v1/rooms/{roomId}/{resource}
    scheme: https
    schemeVersion: '1.1'
    variables:
      roomId:
        description: Id of the Gitter room.
      resource:
        description: The resource to consume.
        enum:
          - chatMessages
          - events

security:
  - httpBearerToken: []

stream:
  framing:
    type: 'chunked'
    delimiter: '\r\n'
  read:
    - $ref: '#/components/messages/chatMessage'
    - $ref: '#/components/messages/heartbeat'

components:
  securitySchemes:
    httpBearerToken:
      type: http
      scheme: bearer
  messages:
    chatMessage:
      summary: >-
        A message represents an individual chat message sent to a room.
        They are a sub-resource of a room.
      payload:
        type: object
        properties:
          id:
            type: string
            description: ID of the message.
          text:
            type: string
            description: Original message in plain-text/markdown.
          html:
            type: string
            description: HTML formatted message.
          sent:
            type: string
            format: date-time
            description: ISO formatted date of the message.
          fromUser:
            type: object
            description: User that sent the message.
            properties:
              id:
                type: string
                description: Gitter User ID.
              username:
                type: string
                description: Gitter/GitHub username.
              displayName:
                type: string
                description: Gitter/GitHub user real name.
              url:
                type: string
                description: Path to the user on Gitter.
              avatarUrl:
                type: string
                format: uri
                description: User avatar URI.
              avatarUrlSmall:
                type: string
                format: uri
                description: User avatar URI (small).
              avatarUrlMedium:
                type: string
                format: uri
                description: User avatar URI (medium).
              v:
                type: number
                description: Version.
              gv:
                type: string
                description: Stands for "Gravatar version" and is used for cache busting.
          unread:
            type: boolean
            description: Boolean that indicates if the current user has read the message.
          readBy:
            type: number
            description: Number of users that have read the message.
          urls:
            type: array
            description: List of URLs present in the message.
            items:
              type: string
              format: uri
          mentions:
            type: array
            description: List of @Mentions in the message.
            items:
              type: object
              properties:
                screenName:
                  type: string
                userId:
                  type: string
                userIds:
                  type: array
                  items:
                    type: string
          issues:
            type: array
            description: 'List of #Issues referenced in the message.'
            items:
              type: object
              properties:
                number:
                  type: string
          meta:
            type: array
            description: Metadata. This is currently not used for anything.
            items: {}
          v:
            type: number
            description: Version.
          gv:
            type: string
            description: Stands for "Gravatar version" and is used for cache busting.

    heartbeat:
      summary: Its purpose is to keep the connection alive.
      payload:
        type: string
        enum: ["\r\n"]

While the info, services, and components collections are pretty standard for an AsyncAPI definition, notice the stream collection. Providing details about the framing type and delimiter, which then connect to the heartbeat and message schema. Providing a machine-readable definition of the messaging stream, with parameters for determining the message room, and resource being part of the server variables you can pass through when initiating the stream.

This AsyncAPI definition was created by the AsyncAPI team and can be found on their Github alongside other sample AsyncAPI definitions. We are about to publish AsyncAPI definitions for 50 APIs that we’ve proxied using Streamdata.io, providing a more comprehensive look at how you can define SSE APIs using AsyncAPI. While the Websocket APIs are taking us a bit longer to craft, the web APIs we are proxying using Streamdata.io are proving to be pretty formulaic when it comes to publishing a machine-readable AsyncAPI–something we’ll continue to showcase here on the blog in future posts.