Build with ServerlessQ on Vercel

ServerlessQ brands itself to be the message queue product for Vercel Users. Let's see a complete example on how to build that.

What we will build in that tutorial:

• ServerlessQ Account + API Token
• ServerlessQ Message Queue to trigger this API
• Consumer API on Vercel. That is an example Vercel project which has two API routes and can be easily deployed.
• Producer API on Vercel. In the same Vercel project we will have a producer API route which will send messages to ServerlessQ and the message queue will forward it to the consumer.

The flow will be the following:

1. The producer wants to start some background job
2. The producer sends a message to the message queue
3. The message queue, queues the message and forwards it to the consumer
4. The consumer receives the message and starts the background job
5. The message queue get's the response and retries in case of errors

Let's go 🚀

ServerlessQ Account + API Token

We first create an account on ServerlessQ to obtain an API token. The account is free!

Head to our dashboard and Sign-Up.

After signing-up you get a pop-up with the API token. Note the API token.

If you already have an account you can check your profile page and copy your API token from there.

Create Message Queue

Next, we will create a message queue which should handle our messages.

If you already have a queue simply copy the queue ID. If not let's create a new one.

Head over to queues and click Create Queue.

Give the queue a name (for example Tutorial) and click on submit.

Your queue is ready now! 👍🏽

Deploy Consumer and Producer API on Vercel

Now we will setup the Consumer and Producer APIs on Vercel.

Checkout the accompanying repository on GitHub. Simply click on the Vercel Deploy button and you will be redirected to Vercel.

On Vercel you need to do two things.

1. Define Git Repository to create

Vercel creates a repository for you. You need to create one to be able to update and deploy your project.

Define your GitHub connection, a name for the repository, and click on create.

2. Define Environment Variables

Next you need to fill two environment variables:

1. SERVERLESSQ_API_TOKEN: Your API token to send messages -> find it here
2. SERVERLESSQ_QUEUE_ID: Your queue ID to send messages to -> find it in your queue

Both of them were created in the first steps.

Now click on Deploy

Your tutorial project will be automatically deployed.

Consumer API

The consumer API has two routes:

https://<VERCEL-URL>/api/consumer/success: Returns a 200 code and indicates a success response https://<VERCEL-URL>/api/consumer/fail: Returns a 400 code and indicates a failure response

Let's have a look at the consumer API functions.

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<void>
) {
  res.status(200).send();
  // fail: res.status(400).send();
}

Let's send a message from the ServerlessQ UI.

Get the URL of your deployed tutorial project from your Vercel dashboard.

Go to your Queue -> Send Message

Paste the URL to the target field and leave the rest on its defaults

Hit Send.

You'will see the response from your consumer.

So our consumer is working. We mocked the producer with sending messages from the UI. This won't be used in a production system of course. So let's build that producer.

Producer API on Vercel

The producer looks also pretty simple. Check the file pages/api/producer.ts to see the source code.

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  const { success } = req.query;

  const targetUrl = `https://${VERCEL_URL}api/consumer/${
    success ? "success" : "fail"
  }`;
  console.log("Target URL: ", targetUrl);

  const fetchUrl = `https://api.serverlessq.com?id=${SERVERLESSQ_QUEUE_ID}&target=${targetUrl}`;

  const result = await fetch(fetchUrl, {
    headers: {
      Accept: "application/json",
      "x-api-key": SERVERLESSQ_API_TOKEN!,
    },
  });

  console.log("Result: ", result);

  res.status(200).json({ name: "Message sent to queue" });
}
}

The producer API is doing the following things:

1. Build target URL by getting the current VERCEL_URL and check if the success query parameter is set
2. Build request to send to ServerlessQ. Send the queueId and the targetUrl as query parameters. The token is in the header with the key x-api-key.
3. Send request to ServerlessQ

That's it. The rest runs asynchronously now.

1. Build target URL

The target URL in that case is also different for the Vercel deployment. For that we use the variable VERCEL_URL here. This variable is published by Vercel automatically. You can also simply define the target URL, and normally you would enter a URL here. Since the URL is different for each Vercel deployment we are using the variable.

2. Build request to send to ServerlessQ

The request to ServerlessQ always follows the same schema:

Query parameter:

• id: The queue ID
• target: The target URL

Header:

• x-api-key: The API token

3. Send request to ServerlessQ

Make your fetch to the REST API. It doesn't matter which client (fetch or axios or similar) you use.

That's it. Let's call it and see what happens.

Sending the message

You can send the message by visiting the producer URL in the browser. For example with my URL simply visit: https://tutorial-vercel.vercel.app/api/producer?success=true. This will execute the producer API function. Your request is now sent to the ServerlessQ API. For your use-case you need to use your URL: https://<VERCEL-URL>/api/producer?success=true. If you don't pass the success parameter you will mock a 400 response.

Let's see it in action.

First, I enter the URL and pass the parameter ?success=true to mock a 200 response.

Second, I enter the URL without the parameter to mock a failure.

Final Words

That's it. You can see how easy it is to get starting with ServerlessQ. Simply send messages via our REST interface to the queue and re-use your existing APIs.

Let us know if you need help with anything!