Today, many companies have employees that work from diverse locations around the globe. If your company’s product relies on APIs (internal and/or external), your team needs to know immediately when a critical API goes down or starts delivering invalid information. But how can you quickly communicate problems of this type to your global team?
The API Science platform lets you create alerts that are sent out to your team that’s responsible for addressing API outages. Email is the obvious means for communicating that a problem exists. But your API Science account also enables you to further broadcast alerts using mainstream team collaboration tools including:
- Slack – a messaging app that supports team collaboration
- Zapier – a platform that enables users to create interfaces between different applications
- HipChat – a chat platform designed for teams
- PagerDuty – a widely-used online incident management platform
- IFTTT – IF This Then That, a site that enables the creation of API recipes
- Todoist – a team “to do” list platform
In this post, I illustrate how these tools can be utilized to broadcast alerts to your API monitoring team in critical situations.
Using Slack to Broadcast API Monitor Alerts
Slack is a widely-used messaging app that facilitates team collaboration regardless of where the team members are located. If your team is monitoring critical APIs, team members will need to be alerted when one or more of the APIs goes down or experiences performance issues. One way to do this is to integrate your Slack team into your API Science account.
On your API Science dashboard page, click your account name at the upper right corner of the page, then select “Settings”:
On the Settings page, click “Contact Book”:
Clicking “New Contact” brings up the “Create Contact” pop-up dialog. Use the pull-down list to select “Slack”:
Creating Your Slack Integration URL
The “Integration URL” is created using your team’s Slack account. Log into Slack and click your team’s account name in the upper left corner:
In the menu window that pops up, select “Apps & integrations” beneath your team’s name:
This brings you to a Slack page where you can select many apps that have been preconfigured for integration with Slack:
In our case, however, we need to create a new, custom integration. To do this, click “Build” to the left of your Slack team name at the top of the page.
The next Slack page asks “What will you build?”
On the right, beneath “Something just for my team,” click “Make a Custom Integration.” On the page this brings you to, click “Incoming WebHooks”:
Scroll down the “Incoming Webhooks” Slack page to the “Post to Channel” box. Select one of your Slack channels to receive the API Science alert messages, and click “Add Incoming WebHooks Integration”:
The next Slack page will include a “Webhook URL” text field. Copy the URL from the text field, return to your API Science “Create Contact” page, and paste the URL into the “Integration URL” field, then click the “Create Contact” button at the bottom of the pop-up dialog:
A Slack contact will be added to your Contact Book.
Using Slack Contacts
To use your Slack contact within your API Science account, return to your API Science Dashboard, select the monitor that will send alert messages to your Slack channel, scroll down to the “Alert Rules” section at the bottom of the monitor’s summary page, and use the “Select a contact to be alerted” pull-down to select your Slack channel. For example:
If a problem occurs for the monitor, the alert message will be posted to your Slack channel, for example:
Clicking on the link in the message brings you to the API Science detail page for that check.
Using Slack, Zapier, and Facebook to Broadcast API Monitor Alerts
Zapier is a platform that enables users to create interfaces between different applications. For example, one popular “zap” (Zapier’s nickname for the interfaces) creates new Trello cards from new Gmail emails. Zapier currently interfaces with more than 500 apps. Since Slack is among these apps, and Zapier’s interface with Slack includes monitoring channels for new messages, the Zapier infrastructure can be used to extend the reach of our API Science alerts to hundreds of apps and sites. So, no matter where your API monitoring team members are at the moment, if they’re connected to social media your alerts will find them.
In this post, I’ll show how to communicate API Science alerts received by Slack to Facebook using Zapier.
First, create a Zapier account, then click “MAKE A ZAP!” at the top of the page to enter the Zapier editor:
Note that for each app that will be part of your zap, you’ll have to provide Zapier with your login information and whatever other information is required to execute the actions your zap will perform. These steps are not included in the discussion below.
The first step is to name your zap and configure the trigger that invokes the zap:
Here, I’ve named my zap “Lyra Monitors” and I’ve selected the zap to be triggered whenever a new message is posted to a specific Slack channel. Clicking “Save + Continue” provides an opportunity to test the connection between Zapier and Slack. Run the test and click “Save + Continue” to select the Slack channel that will trigger the zap:
Here, I’ve selected the “acme_api_monitoring” channel that I created above to receive API Science alerts. Clicking continue provides an option to test the trigger:
If all is configured correctly, Zapier will detect the message, and you’ll move on to configuring your zap’s action.
When my zap is triggered, I want a message to be posted to my Facebook account. Zapier provides multiple interfaces to Facebook, including posting to your timeline and posting to one of your pages. Here, I’ve chosen the latter:
When you click “Save + Continue” you’ll have to provide Zapier with the relevant information about your Facebook account (unless you’ve done this previously). Again, the zap editor provides an opportunity to test the connection with your Facebook account:
Click “Save + Continue” to select the Facebook page that will receive your zap’s posts, and enter the text that will be posted. You can also add a picture, specify a link to be included in the post, add descriptive material, etc.
Clicking “Continue” at the bottom right of the page brings you to a summary page that lets you test the page post configuration:
If the test is successful, you’ll see a new post on your Facebook page, published by Zapier:
Return to Zapier, and click “Finish” to complete your zap. The next Zapier page lets you activate your zap, which then shows up on your Zapier Dashboard:
With the zap activated, every time an API Science monitor sends an alert to Slack, a new post will be created on my Facebook page.
Using HipChat to Broadcast API Monitor Alerts
HipChat is a chat platform designed for teams. Users create “rooms” where team members can present material and interact. The benefit is that the entire team can easily view the history of the discussion, or search for individual posts, at a single location. Compare this with a team attempting to search old emails to reconstruct a past discussion, and the benefit of HipChat to business teams becomes obvious.
If you are monitoring APIs using the API Science platform, your team can take advantage of HipChat. API monitor alerts can be configured to send messages to a HipChat room any time an API check fails, or returns to service. Since HipChat runs on Mac, Windows, iOS, Android, and Linux, your team can stay connected with what’s happening in your API monitoring no matter where they are, on a 24/7 basis.
To demonstrate this, I created an “API Monitor Alerts” room in the API Science HipChat account:
To send messages to the HipChat room, a HipChat contact has to be added to your API Science account. Right-click on your account name at the top right of your dashboard page, and select “Settings”:
On the Settings page, select “Contact Book”; then click the “New Contact” button:
In the pop-up “Create Contact” dialog, use the pull-down and select “HipChat” as the contact type:
The “Integration URL” is provided by HipChat. At the top of the HipChat page, click on “Integrations.” Then, use the “Select a room” pull-down to identify the room for which the integration will apply. The integration can be applied to all rooms or a specific room:
For this demo, I selected my “API Monitor Alerts” room. HipChat includes preconfigured integration with various apps, but in our case we need to build a custom integration. So, the next step is to click the “Build your own integration” box:
HipChat provides two types of “Build your own” integration:
- Notify People in This Room – enables sending messages from an external application to the HipChat room
- Extend HipChat with Your Commands – enables sending messages from the HipChat room to an external application
In our case, we want the “API Monitor Alerts” HipChat room to receive messages sent by our API Science monitor.
At the bottom of this page, enter a name for your integration, then click “Create.”
The next page provides a URL that can be used to post messages to the selected room, along with a curl test that lets you try out your new integration:
When I click the “Try it!” button, a message is sent to my “API Monitor Alerts” room:
Completing the Integration
Now it’s time to configure your API Science monitor to send messages to the HipChat room. Copy the URL from the HipChat integration page and paste it into the “Integration URL” field in the API Science “Create Contact” dialog, enter a label for the contact, then click the “Create Contact” button:
Return to your API Science dashboard and select the monitor you’d like to connect with your HipChat room. Scroll down to the bottom of the page to the “Alert Rules” section. Add a new alert rule. In the “Select a contact to be alerted” pull-down, select the HipChat contact:
Then click “Add Rule” to save the new alert.
When a monitor check fails, a message is posted in the HipChat room, for example:
The link brings your team to the API Science detail page for the check that failed.
Using PagerDuty to Broadcast API Monitor Alerts
PagerDuty is a widely-used online incident management platform that “helps orchestrate the ideal response to create better customer, employee, and business value.” When something goes wrong, that incident can be logged in PagerDuty, and all team members who are responsible for monitoring that system will be notified about the issue.
If your business relies on APIs (internal or external) and your customers expect near permanent uptime for your product, then your team needs to know when critical APIs fail. Integrating PagerDuty with your API Science monitoring services can help ensure that the team members who are responsible for maintaining your internal APIs, and maintaining code that responds to external API outages, are always informed.
The first step is to add a PagerDuty contact to your API Science account. From your API Science Dashboard, click your account name in the upper right corner, then select “Settings” on the pull-down menu:
Your settings page is displayed. Under the “Account” tab, click “Contact Book” and click the “New Contact” button:
The “Create Contact” dialog appears. Select “PagerDuty” in the pull-down menu:
Before the contact can be created, a PagerDuty “Integration key” must be obtained from your PagerDuty account.
Obtaining Your PagerDuty Key
To obtain your PagerDuty key, log into your PagerDuty account and click the “Configuration” tab:
Clicking “API Access” on the “Configuration” tab pull-down menu brings you to the “API Access Keys” page, which enables you to create an API key for integration with your API Science account:
Click “Create New API Key” to generate the key for PagerDuty integration with your API Science account. On the screen that follows, enter a description for your PagerDuty API key, and click the “Create Key” button:
You are brought to a page that shows you the newly-created API key, for example:
Now, access to the PagerDuty API is possible from your API Science account. Copy the PagerDuty API Key text, return to your API Science “Create Contact” dialog, and past the key into “Integration key” field:
You may enter a label for the contact. Clicking “Create Contact” enables your PagerDuty account to be contacted when one of your API Science monitors sends an alert due to an API check failure (or a return to service).
To send API Science notifications to PagerDuty, select one of your API Science monitors. Scroll to the bottom of the API monitor summary page and click “Add Rule”; then, add your PagerDuty contact to the “Alerts Rules” list:
Click the “Add Rule” button, and your PagerDuty account will be notified whenever a validation for this API monitor fails.
After an API check fails, PagerDuty will report (for example):
You can configure your PagerDuty account such that these reports will be forwarded to your entire API monitoring team via phone calls, email, SMS text messages, or mobile app push notifications.
Using IFTTT and Todoist to Broadcast API Monitor Alerts
IFTTT (IF This Then That) is a site that enables the creation of API “Recipes for the Small Business Owner.” Activity that takes place on a particular site is monitored by IFTTT, and if a trigger event occurs, then an action can be initiated that produces a result on a different site. The IFTTT “recipes” that enact this are actually little programs that are created by IFTTT users. A user can implement an already-created recipe (tailoring it to utilize their own accounts), or new recipes can be created.
In this example, I illustrate how to create a new IFTTT recipe that is triggered by a Facebook Page notification sent by Slack in response to an alert created by your API Science account (see the Slack/Zapier/Facebook discussion above); the recipe sends a notification to your team’s Todoist account, notifying team members that a new “to do” item needs to be addressed.
Once you’ve created an IFTTT account, you’ll see a “My Recipes” link at the top of your home page. Clicking this link brings you to your “My IF Recipes” page:
Click the “Create a Recipe” button to get your integration started.
Next, you’re prompted to specify the “this” that will trigger the “that”:
Click the “this” link to identify what event will trigger the “that” action which you’ll later specify.
Now, you select the IFTTT “channel” that will provide the trigger event. In our example, an update to a Facebook Page is the trigger. Clicking the “Facebook Pages” icon brings you to:
Click the “Connect” button, and you will be navigated to your Facebook account. You’ll have to approve information IFTTT will receive in order to confirm the connection. Then, IFTTT will ask you who can view posts they will privately send to you on Facebook. Providing IFTTT with appropriate permissions brings you to a page that lets you select which of your Facebook Pages you’d like to use with IFTTT, for example:
Select your Facebook Page on the pulldown list, then click the “Update” button to connect the page with IFTTT:
Clicking the “Done” button brings up another page where you can click a “Continue to the next step” button. Click that to enter the “Choose a Trigger” step.
Several options are available as IFTTT triggers for a Facebook Page. Since we’ve previously configured our “Lyra Monitors” Facebook Page to post new messages whenever one of our monitors sends an alert, we select the “New status message on page” trigger option, which “fires every time you create a new status message on your Facebook Page.”
Clicking the “Create Trigger” on the next page brings you to the “that” part of the equation. What should happen when your defined trigger event occurs?
Clicking “that” opens a display of IFTTT channels that provide an action that responds to your defined trigger.
Perhaps your team uses Todoist for organizing items on your team’s “to do” list? Select that as your IFTTT action channel. You’ll be asked to connect to your Todoist Channel:
Agree to the terms, then click the “Done” button, and the subsequent “Connect” button, and you can then create the task that will be performed on Todoist when the Facebook Page trigger is activated.
At this point, your IFTTT entries depend on the actions that your selected response site requires. For Todoist, you select a project, task content, and (optionally) more.
Clicking through let’s you create a recipe that will react to any new Facebook Page messages by creating an entry on your team’s Todoist page (or any other app you selected as the response to your trigger).
API Science’s alert capabilities can be easily integrated with mainstream communications technologies including Slack, Zapier, Facebook, HipChat, PagerDuty, IFTTT, and Todoist. Whatever platform your company chooses to use for notifications, when you need to make your team aware of critical API monitor issues, API Science provides a means to deliver those messages.