Ever since I heard Tibco's CEO, Vivek Ranadiv say that a database is like a phone that doesn't ring, I've used it as a way to describe why APIs should be two-way. Another metaphor we've used to describe this is by talking about "full-duplex" APIs, although there's a little mismatch with that.

There are at least three different modes in which an API might send data:

1. Continuous stream - some system need to be in near-constant contact with the other participants. For example, a chat system needs to be ready to send and receive information from the participants at almost any time. Another way to think of these kinds of API interactions is as persistent connections.
2. Broadcast - some systems have data that they must distribute to many participants. A blog post being sent to multiple subscribers is an example of this.
3. Evented - some systems need to push data to one or a few other systems when something happens (i.e. when there's an event). Some APIs are for user (entity) accounts and the data being sent is related to a specific entity and destined for another system where that same user has an account. Some are merely point-to-point connections. The key idea is that there's an event that needs to be seen by a few other systems.

The first and second scenarios have specifications that are widely known, if unequally used. Continuous stream applications can use Cometd or Web sockets. PubSubHubBub (PuSH) is commonly used in broadcast-style applications.

Twilio is probably the best example of an evented API. They're using Webhooks, a good solution for this sort of thing. But many other point-to-point or entity-centry applications are using home grown solutions that tend to be used only by that one API. Take Fitbit, for example. I love my Fitbit, but their "subscription API" is "loosely modeled on PubSubHubbub (PuSH), with simplifications." Don't get me wrong--I'm glad they have one at all--but PuSH probably isn't the best place to start for this application.

Sam Curren and I have proposed the Evented API specification for this sort of thing. Evented APIs are specializations of Webhooks. All APIs that follow the Evented API specification are Webhooks, but not all Webhooks are examples of evented APIs.

Evented APIs are not meant to be used as continuous streams or broadcast subscriptions. They are designed for one-to-one or one-to-a-few interactions. Let's return to Fitbit. I'm a Fitbit user. I have an account. If I want to link my Fitbit account to some other online service where I also have an account, then an Evented API would be a perfect fit (bit).

There's nothing "wrong" with how Fitbit's doing it, but it's not standard. This is an argument about standards, not about the "right way." If we can all agree on a standard for point-to-point and entity-centric API interactions, we can start to create libraries for common programming languages and develop pools of expertise. Sam and I created the Evented API specification to solve this problem. Kynetx supports the Evented API, but the specification is independent and does not rely on any proprietary technology.

APIs that call you are relatively new and consequiently unfamiliar. Undersanding what type of subscription or push interaction you need to support will lead you to the best way to do it. We'll be taking the Evented API specification to a standards body next year. We'd love to get your comments. We'd really love for you to start using it and give us feedback based on real-world experience.