Unlike request/response APIs, which almost always use conventional HTTP exchanges, realtime APIs may use HTTP in unconventional ways or even use non-HTTP protocols. There are four common realtime API mechanisms:

  • HTTP streaming: Client makes an HTTP request, and the server trickles out a response of indefinite length. HTTP streaming is performant and easy to consume.f
  • HTTP long-polling: Client makes an HTTP request, and the server waits before responding with a complete response. HTTP long-polling is fault-tolerant and blends well with request/response endpoints.
  • WebSockets: Client connects to server and establishes a bidirectional message pipe.
  • Webhooks: Service makes an HTTP request to a receiver URL. Webhooks are easy to implement, though the receiver must run an HTTP server.

The best APIs offer simple connectivity. This means your API should make use of the above mechanisms in a way that is easy for your consumers to understand and that allows access via generic tools (e.g. curl). Some “APIs” use complex or underdocumented connectivity protocols, but this is not recommended.

Many software developers are familiar with realtime, but we believe that realtime concepts and user experiences are becoming increasingly important for less technical individuals to understand.


The simple definition

Realtime refers to a synchronous, bi-directional communication channel between endpoints at a speed of less than 100ms.

We’ll break that down in plain[er] english:

  • Synchronous means that both endpoints have access to data at the same time (not to be confused with sync/async programming).
  • Bi-directional means that endpoints can send data in either direction.
  • Endpoints are senders or receivers of data: they could be anything from an API endpoint that makes data available to a user chatting on their phone.
  • 100ms is somewhat arbitrary: data cannot be delivered instantly – but under 100ms is pretty close, especially with respect to human perception. Robert Miller proved this in 1986.

An example of a realtime user experience

A simple example of a realtime user experience is that of a chat app. In a chat app, you ‘immediately’ (sub 100ms) see messages from the person (endpoint) you’re chatting with, and can receive information about when they read your messages (synchronous, bi-directional).

Realtime vs. request-response

Web experiences are beginning to move from request-response experiences to live, realtime ones. Social feeds don’t require a refresh (a request) to update, and you don’t need to email documents as attachments that need to be downloaded (request) and sent back with edits (response) – you just use collaboration software that works in realtime.

More realtime experiences

Realtime user experiences are everywhere you look – especially where near-instant access to information is valuable. You’ll find realtime in:

  • Collaboration: realtime access to internal and external information from your team is becoming the norm. It’s accepted that a sales inquiry (data) can be instantaneously relayed from live chat on your website, into your customer service portal and then into Slack.
  • Finance: stock tracking and bitcoin wallets require immediate access to information. Applications like high-frequency trading exist specifically because of the ability of certain parties to access and act on data faster than others.
  • Events: second-screen experiences for sports, including live betting with realtime odds updates, are becoming increasingly common.
  • Crowdsourcing: distributed collection, analysis, and dissemination of data from distributed endpoints (think reports from WeatherUnderground stations or from the traffic app Waze) is only valuable when it occurs in realtime.

Realtime in the future

As we see it (and admittedly, we are a little biased), realtime is quickly becoming the new normal. Up-to-date information is expected by businesses and end users. Realtime is the natural complement to trends like:

Big Data: as the number of digitally connected businesses, experiences, and devices rises, so does the amount of data generated. Data becomes more valuable as the three V’s of a dataset (velocity, volume, variety) increase – and realtime transmission is central to the velocity component.

In the past, companies benefitted from hoarding data, but increasingly data is becoming most valuable when shared (and monetized). The companies that can aggregate and share the most data, as quickly as possible, will be successful.

Proliferation of APIs: businesses sharing data are increasingly going to do so through APIs. Entire businesses are being built on APIs by platform providers like Twillio (they only have an API) or they are coming to comprise substantial portions of existing businesses (like Salesforce’s API).

An elegant end-user experience is increasingly the product of data that’s being moved through multiple APIs – and the number of APIs is only going to increase as they trend towards becoming less technical and more accessible and interoperable. The APIs that provide access to data or move it through their system as quickly as possible will rise over those that cannot.

Additional API Design Resources

API design for an event-driven world by George Ornbo –  “Watching the web unfold before my eyes every day is still as thrilling as the day I managed to FTP my first HTML file across a dial-up connection and onto the Internet. Request response cycles have got the web to where it is now but it is changing at an incredible pace. More and more devices are connected to the web, some with humans attached to them, some without. If we are to make sense of this chaos where fridges talk to supermarkets, lightbulbs send you notifications that you just got paid, bus stops show you where your bus is in real-time we must start thinking of the web in terms of events.

REST and HATEOAS work for documents where documents are transferred on a request response cycle. Where devices are connected with a persistent connection they are deficient because they are procedural. Events are not procedural. They are chaotic and can happen at any time and arrive from anywhere.

The web needs to break out of the request response cycle and embrace events. Event-driven APIs are really RPC APIs and there are no conventions around their design. There is a lot of work to be done.”

Slack’s Real Time Messaging API by Slack –  “The Real Time Messaging API is a WebSocket-based API that allows you to receive events from Slack in real time and send messages as users. It’s sometimes referred to as simply the “RTM API”.  It is the basis for all Slack clients. It’s also commonly used with the bot user integration to create helper bots for your workspace. If you prefer events to be pushed to you instead, we recommend using the HTTP-based Events API instead. Most event types supported by the RTM API are also available in the Events API.”

Best Practices in Building Websockets APIs by Elad Wertzberger – “Technical sessions reviewing protocol, authentication, browser-limitations [headers,ping/pong], proxy/nginx, testing, and dropwizard-websockets.  Presented at TADSummit 2016, 15-16 Nov, Lisbon in Stream 4, Contextual Comms, Conversational CRM, BOTs, reviews the practical impact of the changes happening to communications. Messaging and IP Communications as a Platform providers are diversifying the options for communications, and how businesses communicate with their customers. We are only at the early stages of this change, however, multi-channel communications, session management, automation (BOTs) and real-time analytics are delivering business results today. Attendees can learn from leading implementers where to focus efforts, and not get taken-in my the weak-minded marketing BS plaguing in this space.”

Replace RESTful APIs with JSON-Pure by Michael S. Mikowski – “RESTful APIs, the big lie challenged the widely-held belief that RESTful APIs are a good idea for modern web applications. The inspiration to write the post came from two sources. First, we were writing an new API for an SPA, so the topic was certainly at the top of my mind. Second, we are recruiting development team members, and the candidates placed a surprising amount of importance on RESTful APIs. … The move away from RESTful APIs has already begun. Both FaceBook’s Relay and Netflix’s Falcor dispense with any pretense of being RESTful. I expect that REST will continue to be used for the majority of web traffic, especially content distribution. However, the more sophisticated APIs used by SPAs will move to more appropriate, non-RESTful design patterns. And that’s a good thing.”