An application programming interface, or API, is a software program that defines a way to programmatically perform an interaction with a particular system, or interface with it. Web APIs, then, allow a browser or server to programmatically alter and extend the behavior of a web page.

For example, the nearly ubiquitous Document Object Model, or DOM, makes the various elements of a web page available to a programming language such as JavaScript, so that they can be programmatically manipulated.

For another example, the Geolocation API is the API used when a “store locator” program on the WalMart or Home Depot website asks for the user’s location, in order to find the nearest store to the user.

Here are some other commonly used Web APIs.

XMLHttpRequest

The XMLHttpRequest API, or XHR API, was JavaScript’s original implementation of AJAX. The XHR API allows processing of HTTP requests and responses asynchronously. It does this by raising a load event when the requested data is successfully fetched. The main program can then use an “event handler” function to update the web page where needed. (For more information, see Asynchronous JavaScript.)

Fetch

The Fetch API uses the Promise object specification to send and retrieve data. The Promise object is more generic than the XMLHttpRequest object; it allows deferral of any process rather than just HTTP requests and responses. Since the Fetch API is more flexible and therefore has wider application than the XMLHttpRequest object, it is generally the preferred way to fetch data asynchronously.

One of the primary characteristics of the Promise object is that it exposes a then method, which itself returns a new Promise object. This allows the chaining of Promise objects one after the other. The then method also accepts two optional arguments, onFulfilled and onRejected.

Here’s an example of the fetch method:

The getListOfStuff function accepts a success argument, which is the function that it calls upon successfully fetching data. The function calls the fetch method. This method returns a Promise, passing a Response object to the first argument. This object has a json method, which converts the Response object’s data stream to data in JSON format. (The Response object data doesn’t have to be converted to JSON format; this is just a common example. It can be converted to any data format the client and server agree upon.) The next Promise object takes this data and passes it to a function call of the function passed to the success argument. This function populates the web page with the response data.

The asynchronous behavior happens with the callback function called on line 4. That function doesn’t get called until the server has responded with the data.

For more information on the XMLHttpRequest and Fetch APIs, see Asynchronous JavaScript.

SSE

Since AJAX is designed to handle “pulls,” where the client asks for data from the server, it is not the most efficient way to handle “pushes,” where the server initiates a data transfer to the client without being asked.

The Server-side events, or SSE, API is more efficient than long polling if the flow of change events is unidirectional, coming from the server to the client. The client signs up to see the changes (called subscribing) and the server sends them as they come up (called publishing). This requires a single persistent connection, and while there is still server overhead in maintaining the connection, SSE avoids the overhead of resending request and response headers every time there is a change as is necessary in long polling.

SSE is useful for stock ticker, weather, traffic map applications and the like, applications where most of the changes come from the server.

WebSockets

AJAX is not the most efficient model for true bi-directional communication, such as that used, for example, in an instant messaging (IM) application. There would need to be two one-way connections, and each of them would need to poll the other for any changes.

The WebSocket API makes it possible to open a two-way interactive communication session between the user’s browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.

The WebSocket API runs as a thin protocol layer of its own over the TCP protocol. This protocol is distinct from HTTP, although it is designed to run over the same ports as HTTP (80) and HTTPS (443). On port 443, it uses TLS as does HTTP. While distinct from HTTP, WebSockets are also compatible with it. A client requesting a WebSocket connection uses the http:// orhttps:// scheme in the URL, and adds two headers: Upgrade: WebSocket and Connection: Upgrade. A server accepting the WebSocket request sends the same two headers in its response; if it doesn’t support WebSockets (most do by now), the connection is established as an HTTP or HTTPS connection.

Once both client and server agree to establish a WebSocket connection, the WebSocket handshaking process takes place and the connection is established. Both sides can then send and receive data directly through the connection.

The Zoom videoconferencing application is an example of an application that uses WebSocket connections for interactive communication.

The next article is the last one in this series. It covers (briefly) HTTP performance optimizations and peer-to-peer architecture.