How to build a Postman app for Zapier

What is a Zapier “app”?

What we’ll build

• Polls Postman's APIs for new collections at regular intervals

• Allows users to set their preferred polling frequency—ranging from every 1-15 minutes (based on the Zapier plan), to once an hour, daily, or weekly

• Establishes a Zapier trigger for integration with over 7,000 apps

Prerequisites

• Zapier account

• Postman account with an existing collection for testing

1. Install the Platform CLI and Log In

nvm use v18

npm install -g zapier-platform-cli

zapier login --sso

zapier login

2. Initialize a New Zapier App

zapier init postman-zapier

cd postman-zapier

npm install

code -r .

3. Zapier trigger command

zapier scaffold trigger collection

zapier test

4. Authenticating with Postman

const authentication = {
  type: "custom",
  fields: [
    {
      key: "apiKey",
      label: "API key",
      required: true,
      helpText:
        "Find the API Key in your [app settings page](https://postman.co/settings/me/api-keys)",
    },
  ],
};

const test = (z, bundle) => {
  return z
    .request({
      url: "https://api.getpostman.com/me",
      headers: {
        "X-Api-Key": bundle.authData.apiKey,
      },
    })
    .then((response) => {
      if (response.status === 200) {
        const data = z.JSON.parse(response.content); 
        const username = data.user.username; 
        return {
          username: username,
        };
      }
      // If the response is not 200, throw an error
      throw new z.errors.Error("Invalid API Key", response.status);
    });
};

const authentication = {
  type: "custom",
  fields: [
    {
      key: "apiKey",
      label: "API key",
      required: true,
      helpText:
        "Find the API Key in your [app settings page](https://postman.co/settings/me/api-keys)",
    },
  ],
  test: test,
  connectionLabel: "{{username}}",
};

const addApiKeyToHeader = (request, z, bundle) => {
  if (bundle.authData.apiKey) {
  request.headers['X-Api-Key'] = bundle.authData.apiKey;
  }
  return request
}

//authenticating with Postman
  authentication: authentication,

  beforeRequest: [addApiKeyToHeader],

5. Testing authentication

API_KEY='your-api-key-here'

 const bundle = { inputData: {}, authData: {
      apiKey: process.env.API_KEY,
    }, };

const zapier = require("zapier-platform-core");

// Use this to make test calls into your app:
const App = require("../index");
const appTester = zapier.createAppTester(App);
// read the `.env` file into the environment, if available
zapier.tools.env.inject();

describe("custom auth", () => {
  it("passes authentication and returns json", async () => {
    const bundle = {
      inputData: {},
      authData: {
        apiKey: process.env.API_KEY,
      },
    };

    const authTestResult = await appTester(App.authentication.test, bundle);
    expect(authTestResult)?.toBeDefined();
  });
});

zapier test

6. Building the trigger

  inputFields: [
      {
        key: "polling_frequency",
        label: "Polling Frequency",
        type: "string",
        choices: {
          default: "Default (Zapier default interval)",
          hour: "Once an hour",
          day: "Once a day",
          week: "Once a week",
        },
        helpText: "Select how often you want the polling to occur.",
        required: true,
        altersDynamicFields: false,
      },
    ],

const perform = async (z, bundle) => {
  const currentTime = new Date();
  const lastPoll = await z.cursor.get();
  const pollingFrequency = bundle.inputData.polling_frequency || "default";

let shouldPoll = false;
switch (pollingFrequency) {
  case "hour":
    shouldPoll = !lastPoll || currentTime - new Date(lastPoll) >= 3600000;
    break;
  case "day":
    shouldPoll = !lastPoll || currentTime - new Date(lastPoll) >= 86400000; // 24 hours in milliseconds
    break;
  case "week":
    shouldPoll = !lastPoll || new Date(lastPoll) < new Date(currentTime.getTime() - 7 * 86400000); // 7 days in milliseconds
    break;
  default:
    shouldPoll = true;
    break;
}

if (shouldPoll) {
  try {
    const response = await z.request({
      url: "https://api.getpostman.com/collections",
      method: "GET",
    });
    await z.cursor.set(currentTime.toISOString()); // Update cursor after successful poll
    return response.data.collections;
  } catch (error) {
    throw new z.errors.Error("Failed to fetch collections."); // Error handling
  }
} else {
  if (lastPoll) {
    await z.cursor.set(lastPoll); // Re-set cursor to keep it from expiring
  }
  return [];
}

sample: {
  id: "example_id",
  name: "Example Collection",
  owner: "example_owner",
  createdAt: "2020-01-01T00:00:00Z",
  updatedAt: "2020-01-02T00:00:00Z",
  uid: "example_uid",
  isPublic: true,
}

outputFields: [
      { key: 'id', label: 'ID', helpText: 'The unique identifier for the collection.' },
      { key: 'name', label: 'Collection Name', helpText: 'The name of the collection.' },
      { key: 'owner', label: 'Owner', helpText: 'The owner of the collection.' },
      { key: 'createdAt', label: 'Created At', type: 'datetime', helpText: 'The date and time when the collection was created.' },
      { key: 'updatedAt', label: 'Updated At', type: 'datetime', helpText: 'The date and time when the collection was last updated.' },
      { key: 'uid', label: 'UID', helpText: 'The unique identifier for the collection in Postman.', primary: true},
      { key: 'isPublic', label: 'Is Public', type: 'boolean', helpText: 'Indicates whether the collection is public or private.' }
    ]

npm install -g zapier-platform-core update

Here are the issues we found:
┌────────────────┬──────────────────────────────────────────────────────────────────────────────────────────┐
│ Category       │ Warnings                                                                                 │
│ Method         │ triggers.collection                                                                      │
│ Description    │ need to verify date/time format in latest successful task, but doesn't have a Zap (T003) │
│ Link           │ https://platform.zapier.com/docs/integration-checks-reference#T003                       │
└────────────────┴──────────────────────────────────────────────────────────────────────────────────────────┘

7. Publishing

zapier register

• The title of your integration (minimum of 2 characters required).

• A short description of your app (140 characters max).

• The homepage URL of your app (optional).

• Whether you're building a public or private integration.

• Your relationship with the app you're integrating with Zapier.

• The category that best fits your app.

• Whether to subscribe to updates about your integration.

zapier push

8. Trying it out

Conclusion

• Extend Collection Monitoring: Utilize additional Postman collection endpoints to track more specific events and data, adding depth to our app's triggers.

• Explore More Postman APIs: Branch out from collections to poll addition Postman APIs

• Use Postman’s SDK: Employ Postman's Collection SDK for advanced trigger development, enabling sophisticated data handling.

• Build Actions: Introduce actions that allow users to make changes in Postman based on triggers from other Zapier connected apps