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.
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.
COVID-19 Vaccine Locator India public workspace Overview page
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.
Running a collection via the Collection Runner
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.
Creating a Postman monitor
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:
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
Pre-request script of collections to target the mock server
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.
Postman provides a wide range of functions and features to assist with API development, testing, and collaboration. Here are some commonly used functions in Postman:
Creating and Managing Requests: Postman allows you to create API requests by specifying the request method, URL, headers, parameters, and body. You can manage and organize requests within collections, including creating folders, adding descriptions, and reordering requests.
Request and Response Visualization: Postman provides a user-friendly interface to view and analyze request and response data. It supports syntax highlighting for various data formats such as JSON, XML, and HTML, making it easier to understand and validate the data.
Environment and Variables: Postman allows you to define variables and environments. Variables enable you to store and reuse dynamic values across requests, making them flexible and easy to maintain. Environments provide sets of variables specific to different environments (e.g., development, staging, production).
Pre-request Scripts: Postman enables you to execute scripts before sending API requests using pre-request scripts. These scripts can be used to dynamically generate values, manipulate data, or set variables based on specific conditions.
Collection Runner: The Collection Runner allows you to execute a series of requests in a collection. It enables you to perform data-driven testing by iterating over multiple sets of data or environments. You can configure iterations, delays, and data sources for more comprehensive testing.
Mock Servers: Postman allows you to create mock servers for simulating API responses without a live backend. Mock servers are useful during development, allowing frontend developers to work independently by providing simulated API responses.
Documentation Generation: Postman can automatically generate documentation for your APIs based on your requests and collections. It provides a simple way to share API specifications and details with stakeholders.
Collaboration and Teamwork: Postman offers collaboration features such as sharing collections, collaborating on requests, and commenting on specific requests or collections. It also supports version control integration to manage changes and updates effectively.
Integration and Automation: Postman integrates with various tools and services, including version control systems (e.g., Git), CI/CD platforms (e.g., Jenkins), and API management solutions. It provides options for integrating with these tools to automate API testing and deployment processes.