Creating a Basic Push API

If you're just starting off, you might not have an API in place for external platforms like Integry. We put together this guide to help you with a starting point on how you can create an API that can be consumed by 3rd party platforms like ours. Your requirements might be different so please adapt this guide as you see fit.

Push APIs

Integry interacts with your platform in two ways: via Triggers or Actions. A Trigger is initiated by your platform. Think of this as an event that occurs on your app which you want to push to us. An Action is a reverse: it's when Integry has to send your platform a new event ie we perform an action on you. You can also think of a Trigger as a Push from your app to Integry. For the remainder of this guide, we will focus on Triggers.

A Push architecture allows you to save bandwidth by only notifying Integry when an event occurs. This is much more efficient than old architectures such as RSS where you had to continually poll the API for new changes. Even if the poll occurs every 5 minutes, that's 288 requests per day by every client of your API. It's like asking every 5 minutes "are we there yet?". As you might also notice, the API is not realtime and might have a lag of up to 5mins. Not ideal in today's world.

What's in the Push

The actual REST Push is really simple. It has the following components:

• URL: The URL to which you are pushing to. This is coupled with an HTTP verb like POST or GET.
• Authentication: Authentication information (headers, unlisted URL or key in query parameters)
• Payload: This is a JSON object you're sending of the event. This can include the event object itself, a user ID or account ID to which this event belongs to, etc

Whenever you have an event to push, you can push the JSON payload to the Integry URL via POST. That's it.

While the notification itself is simple, Integry itself needs the ability to create, update and delete these Push subscriptions.

Managing Push Subscriptions

The Integry Widget needs to be able to create subscriptions, delete them and update them. The following section explains what a typical subscriptions API needs.

What do you want to create the subscription against?

Your app has a number of Resources, for example, a CRM has Contacts and Accounts; a project management software has Tasks and Projects, etc. For a Push notification to be created, the Create method needs to specify which resource it will be receiving notifications against.

For example, Project Management software might have a number of Projects. (proj1, proj2 etc). When creating a subscription, the creation call will need to specify that it needs events against proj1. In order for it to do that, there has to be the ability to List Projects. This is usually implemented via a GET call to the projects API such as /project, this should return a list of Project Objects.

Create Subscription

Now that we've specified the Resource, what events do we want to listen to? Typical events include: create, delete and update. For example, whenever a Task is created under proj1, we want a Push event.

We have all the ingredients to create a subscription now. To recap, create a Push Subscription, you will need:

• Webhook URL to send data on
• User access token
• Project / any other resource
• Selected events

The subscription creation will then add an entry in the database and will start sending data out to the subscribed webhook URL when any of the selected events occur. In response, the rest API will return a unique subscription id.

Update Subscription

Update subscription endpoint can be helpful to update subscription’s selected events. Possible input parameters to this endpoint can be:

• Subscription id
• Selected events

Delete Subscriptions

A subscription can be deleted if it’s no longer required. A subscription id will be passed to this endpoint and the endpoint will delete the subscription and will return either success or failure. This is usually using the DELETE verb

Other Stuff

Here are a few more things you want to make sure you're doing with your API:

1. When sending Json, make sure the content type is "application/json"
2. It's good practice to verify that the json being sent is correct. You can validate your json using Jsonlint or any other service

And that's it!