Building Your First Glee Application

Crafting Your API Specification

Let's start with a straightforward WebSocket API using Glee. Imagine a WebSocket server that receives the current time from a client and responds with a greeting like "good morning", "good evening", or "good night" based on the time provided.

In Glee, which is a spec-first framework, the journey begins with defining your API specification. If you're unfamiliar with what an API spec is or how to create one, we recommend going through the tutorials available here before proceeding. For this project, here's how we define our API:

1asyncapi: 3.0.0
2info:
3  title: Greet Bot
4  version: 1.0.0
5servers:
6  websockets:
7    host: localhost:3000
8    protocol: ws
9channels:
10  greet:
11    address: /greet
12    messages:
13      greet:
14        payload:
15          type: string
16      time:
17        payload:
18          type: object
19          properties:
20            currentTime:
21              type: number
22            name:
23              type: string
24operations:
25  receiveTime:
26    action: receive
27    channel:
28      $ref: '#/channels/greet'
29    messages:
30      - $ref: "#/channels/greet/messages/time"
31  sendGreet:
32    action: send
33    channel:
34      $ref: '#/channels/greet'
35    messages:
36      - $ref: "#/channels/greet/messages/greet"

Store this in a file named asyncapi.yml.

This spec shows that our app can perform two operations on a single channel: receiving time and sending a greeting. We've used JSON Schema to define what time and greet messages look like.

Note the operations section. It's essential in Glee, linking your business logic to your spec. For instance, receiveTime is the function invoked when the /greet channel receives a message.

Tip: Including a send operation isn't mandatory but is recommended for validating outgoing messages against your spec.

Initiating Your Glee Project

For ease and efficiency, start your Glee app with our CLI, which automates the setup. In your asyncapi.yml file's directory, execute: asyncapi new glee --name GreetBot --file asyncapi.yml

It will prompt you with a list of server names and let you select which servers you want Glee to create a server for. select the websockets and continue.

Then, navigate to your application's folder and install the dependencies:

1cd GreetBot
2npm install --ignore-scripts

You now have a Glee app scaffolded and ready for development.

Implementing the Operation Function

Navigate to functions/receiveTime.js and input the logic to analyze the time and generate the appropriate response.

1import { GleeFunction } from '@asyncapi/glee';
2
3const receiveTime: GleeFunction = async (event) => {
4  const { name, time } = event.payload;
5  const t = new Date(time);
6  const curHr = t.getHours();
7  let response = '';
8  if (curHr < 12) {
9    response = `Good Morning, ${name}!`;
10  } else if (curHr < 18) {
11    response = `Good Afternoon, ${name}!`;
12  } else {
13    response = `Good Evening, ${name}!`;
14  }
15  return {
16    send: [
17      {
18        server: 'websockets',
19        channel: 'greet',
20        payload: response,
21      },
22    ],
23  };
24};
25
26export default receiveTime;

Note: Want to know more about functions? Click Here!

Each file in the functions directory is a handler where you can craft your business logic. Every handler should export an asynchronous function that takes an event parameter, giving you access to the payload and server details.

Running and Evaluating Your App

To launch and test the app's functionality, follow these steps:

Run your Glee application using:

1npm run dev
2# or 
3npm run start

To test, open a WebSocket connection to ws://localhost:3000/greet in Postman and send {"name":"John","time":"1567906535"}. Watch as your Glee app responds appropriately.