COVID-19 Vaccines in India: How to Build an API-based Vaccine Locator

The Co-Win portal is a critical website for India at this time, allowing Indians to register and schedule vaccinations against COVID-19 (please note that the portal may lead to a 403 Forbidden error if you’re not in India), and it has published the Co-Win APIs. Since the population of India is so large and the situation is extremely tense right now, the available vaccination slots get booked in seconds. During the initial days of the vaccine, Postman Chief Software Architect Shamasis Bhattacharya and Postman Software Engineer Intern Himanshu Sharma used the Postman Collection Runner to receive alerts on the availability of vaccines in their respective areas—and they managed to get vaccinated. Though the portal’s traffic has increased considerably since, and getting a vaccine appointment has become more difficult,  we still think that automating updates when a resource is available is especially useful during the pandemic. We hope you can apply this approach to other helpful APIs in addition to the Co-Win API used in this tutorial.

Getting started

We wanted to share the Postman Collections, monitors, and APIs used by our Postmanauts to configure alerts and visualize available vaccines, so we created a public workspace for anyone to access. The new COVID-19 Vaccine Locator India public workspace contains collections that allow you to receive updates based on configurable parameters, including age limit, vaccine type, and the number of vaccinations required. You can fork the collections you find useful to receive alerts on Slack and Telegram.

Configure alerts

The Co-Win 2-week Alert collection and the Co-Win n-day Alert collections are useful for receiving alerts once the vaccines are available. The respective collection documentation explains the difference between the two and their filtering criteria:

• Co-Win 2-week Alert sends alerts for vaccines available in the next two weeks
• Co-Win n-day Alert sends alerts for vaccines available in the next n days

In order to configure alerts, fork the collection and the Co-Win environment. Once forked, you need to run the collection at regular intervals in order to receive regular alerts. This can be done in three ways:

1. Configure alerts via the Postman Collection Runner

The Postman Collection Runner lets you run a collection by specifying a delay in milliseconds between collection runs. This is recommended because you can set the smallest delay between runs which would enable you to get notified quicker if vaccination is available. Since Postman the Co-Win API may return a 403 Forbidden for a client other than India, be sure to not select the Cloud Agent, instead choose the Desktop agent if you are using the web version. Please Note: Requests fired from the desktop will only work for clients in India.

The only downside to this approach is that you will have to keep your machine running the entire time.

2. Configure alerts via Postman CLI: Newman

Postman monitors run requests on Postman servers, where the Co-Win API may return a 403 Forbidden since these APIs only work for clients in India. Even though Postman monitors allow us to configure regions, the closest region we can get is the Asia Pacific but not specifically India. In that case, we can still reuse all the code in the collections and the environment by running it locally/remotely (on a server in India) using Newman. Since the collections run on a remote server we need not keep the machine running all day as opposed to the previous approach using the Collection Runner.

In order to use Newman, you need to first install it locally or on any other environment (you can try AWS ECS scheduled task, Google’s App Engine Cron Service). Once installed, to run the collection referencing the environment, either export the collection or find the collection URL. Using the URL directly is far more convenient because then you can modify the collection in Postman and without exporting expect to see that change reflected whenever Newman runs.

To find the URL for a collection/environment in your personal workspace, you will need the Postman API Key. The API token can be used to fetch a collection or environment using the Postman API by using these formats:

newman run 
"https://api.getpostman.com/collections/$collection_uuid?apikey=$apikey" 
--environment 
"https://api.getpostman.com/environments/$environment_uuid?apikey=$apikey"

Pro Tip: Set the environment variable values to the initial value you prefer. Newman only picks up the initial value defined in the environment, since the current value doesn’t get synced to the Postman server. In addition, you might want to keep a check on the rate limits for the Postman API.

3. Configure alerts via monitors

Click on the “Monitors” tab on the left, and create the monitor. Select Co-Win as the environment and the collection to monitor. Configure how often you want the monitor to run. For every subsequent run, the monitor will find vaccines matching above mentioned criteria.

Pro Tip: Set the environment variable values to the initial value you prefer. Monitors only pick up the initial value defined in the environment, since the current value doesn’t get synced to the Postman server.

Receive Slack and Telegram alerts

In order to receive alerts on Slack or Telegram, you need to provide some details (i.e., an auth token/key) or configure a webhook, bot, etc.

How to set up a Slack webhook

To send an alert on a Slack channel, we need to configure an incoming webhook for Slack. Once the incoming webhook is set up, you can copy the webhook URL and set the environment variable slack_hook to that value.

How to set up a Telegram Bot

To send an alert to Telegram, you can create a Telegram bot by sending a text to BotFather. Read How to create a Telegram bot? to learn how to receive a bot API token. Set the environment variable telegram_token to the token received. Next, we need a chat ID to send the text message to the bot. To obtain the chat_id, type a message in the custom bot chat and send. Now, hit the following API to get the chat_id in the response:

https://api.telegram.org/bot{{telegram_token}}/getUpdates

Set the chat_id received to the environment variable telegram_chat_id.

How to test existing collection workflows

There is a fair bit of logic involved in the tests and the pre-request script for each of the requests. You’ll need to do some filtering and merging based on the criteria defined in the environment. The goal of these collections is for anyone to not only receive alerts but also be able to customize certain conditions based on their requirements. For that, the code needs to be maintainable. As a user, you don’t want to break existing functionality while modifying or adding certain filters. Since hitting the actual Co-Win API for testing isn’t feasible, especially because the server could be down sometimes due to traffic or geo-locks, we created a mock server by importing the OpenAPI definition for Co-Win API. The Co-Win API collection is the source of truth for the mock server. Any example added to a request should reflect in the mock server behavior.

In order to test the collection, you need to do the following:

• Switch the base_url to point to the mock_url in the environment
• The pre-request script of both collections—Co-Win 2-week Alert as well as Co-Win n-day Alert—have request IDs listed

How does the pre-request script test for different scenarios?

The pre-request script adds a universally unique identifier (UUID) to the x-mock-response-id header. This will make sure that the mock server always returns the example response matching the path and the UUID requested in the header. Since we have the success example UUID uncommented, the mock server will return only the success response each time, and we can run the collection and test if all the logic in the scripts performs as expected for a success scenario.

What should you use to run the collection while testing?

Postman’s Collection Runner, unlike a monitor, will point to the current value in the environment and can work on the Postman desktop agent which means you may not receive a 403 Forbidden because of the geo-lock while hitting the Co-Win API and you can use the same runner against the mock server by modifying the base_url current value.

How to contribute to this public workspace

There are multiple ways you can contribute to the important work of the COVID-19 Vaccine Locator India public workspace or any other public workspace:

• Add collections alerting for different use cases
• Add alerts for other products/platforms (Whatsapp, Messenger, etc.)
• Separate out the testing via mock server logic from pre-request to a different collection to enable ease of use
• Add more visualizations
• Add comments wherever helpful

You can fork an existing collection and make changes to experiment with different options. Once complete, raise a pull request to the collection in the workspace. To contribute by adding a new collection to the COVID-19 Vaccine Locator India workspace, fork the CONTRIBUTIONS collection and raise a pull request against it.

It is a critical time to band together and apply all of our technical proficiency in order to discover new ways to fight the pandemic. We hope this approach inspires you to build automated solutions to ease the process when constantly waiting for resources—whether now or for future circumstances.