The Evented API Specification


The Evented API specification provides a standard method for APIs to signal events using any programming language or system that supports HTTP. Signaling events from APIs provides a means for them reach out when something happens instead of waiting for a request.


Over the last few weeks, I've been blogging a lot about the benefit of evented systems:

The underlying message of each of these articles is that events work better for building networks of products and services (what we have called "mashups") than request-response-style systems. Event-based programming styles fit the dynamic nature of the interactions we want to have online. Event-based systems work on "this happened" where request-response-style systems work on "do this." The former better supports the looser coupling we'll need to build huge networks of products and services.

Fine, you say, but until more companies build events into their APIs, I'm stuck using their old-school request-response API. More to the point, if everyone does it differently, coding up a system that can use all those events in a loosely coupled way will be impossible.

To that end, Sam Curren and I have developed the Evented API specification. The spec says how event generators and consumers should operate and, as a result, how they interoperate. All interactions are over HTTP to make the spec as flexible as possible. You can use any language to generate and consume events. We've tried to design the spec so that it is easy to implement--particularly for event generators. We'd like every existing API to signal events when appropriate. Here are a few examples:

  • Withings - the Withings people really ought to generate an event when a new data point gets added to my data.
  • Endomondo - wouldn't it be cool if Endomondo published an event at the start and stop of a ride or run? I could do more than Tweet my exercise, I could use it to drive other programs.
  • Flickr - Flickr ought to publish an event whenever my collection is updated. Now other programs know when to come grab a new picture. Photography workflow ensues.
  • Foursquare - send events when you check in so that check-ins can drive other programs around the Web.
  • Airlines - send events about delays, ticket purchases, and so on so services like TripIt can more easily mash up with them and guide my trips.
  • Banks - Mint! Just stop the screen scraping already.
  • Fitness data - don't even get us started...

I could go on. There are literally thousands of APIs that have useful information to tell us without our having to ask first. We are stuck in a state of affairs that is the legacy of where we've been (the Web), not where we need to go.

Adding an event generator to an existing service is trivial. Every modern programming language has a way to make HTTP requests and that's all that's necessary. I think many services could add events in a few days of programming time.

If you're familiar with Webhooks, you might ask "how's it different from a webhook?" Webhooks are used for both events and RPCs, and (intentionally) lack constraint on how they are used. Evented APIs are only used for transferring events, and the API allows for a generalized way of transferring events with a common format. The Event API spec fits within the Webhook model and thus any event consumer in the Evented API space has implemented a Webhook. Event generators are calling Webhooks.

If you visit the Evented API site, you'll find an example event generator and event consumer so you can visualize how event subscription, generation, and consumption work. Visit the consumer and create a event signal URL, cut and paste it into the event generator, and start playing.

The Evented API spec is separate from Kynetx. We support it (or will, very shortly), but the Evented API spec is designed to be independent. No proprietary technology is needed to generate or consume events using the spec. Evented APIs is for everyone--not just Kynetx customers and partners. Help get the word out!