APIs and polling

Brief API reminder

Application Programming Interfaces (APIs) in web applications are typically typically built using the request-response pattern, where a client sends a request which the server then responds to. APIs in web are often implemented following Representational State Transfer (REST), where resources are identified through URIs, representation formats are agreed upon (e.g. JSON), and standard methods such as the HTTP methods are used for both semantics and for exchanging information.

A REST API that would provide information about tasks could use specific paths for identifying tasks, HTTP methods for interacting with the API, and JSON as the data format. Figure 1 shows an interaction between a client and a server, where the client sends a GET request, asking for content at a specific path, and the server responds with JSON formatted data.

See also Roy Fielding's dissertation Architectural Styles and the Design of Network-based Software Architectures, which provides a more in-depth discussion of Representational State Transfer.

The request-response pattern is commonly implemented synchronously, where the client sends a request and then waits for a response.

Long and short polling

In the case where a response would take a long time to create, or if there would be some reason to retrieve information repeatedly, the client could poll the server, asking for updates. There are two key mechanisms for polling: (1) long polling and short polling.

Long polling refers to the client sending a request and the server keeping the connection open until a timeout or until there is data that should be sent to the client. Once the connection times out, it is closed, and the client makes a new request. On the other hand, if the server sends a response to the client, the client could decide based on the data whether it should make a new request to the server. This is illustrated in Figure 2.

Short polling on the other hand refers to sending a request, to which the server immediately responds. The connection is not kept open. If the server has data that should be sent to the client, the server will respond with the data. Otherwise, the response from the server would indicate that the requested data is not yet available. Upon receiving a response, the client decides based on the response whether it should make a new request. If yes, the client would wait for a moment, and send a new request.

Although both long and short polling can be used to retrieve up-to-date or nearly up-to-date information from the server, both of them come with a few downsides.

They need to establish a connection to the server and send the HTTP request related header information on each request, which can lead to a waste of resources especially in the case of short polling. With long polling, the connection to the server is always open, leading to potentially unnecessary open connections, while with short polling, a server could be bombarded with requests if the interval between the polling is too small. In addition, for long polling, the connection will time out at some point, which requires implementing a mechanism for resending timed out requests.