Data Representation and Efficient Communication in APIs

Introduction

Clients and servers communicate by exchanging data using a request-response model. An essential aspect of this communication is the data format(s) used for exchanging information. This significant factor sets the difference between an effective and an inept API. One aspect of API design is the choice of a data format that both the client and server can understand conveniently.

The choice of data format is only the first step to a standardized information flow between the sending and receiving parties. Rapidly changing industry demands make it inevitable to change or update the chosen data formats over time. Making changes to the server-side may also require updating the client-side. It’s relatively easy to reflect changes for the browser-based client interfaces where a simple refresh may be enough to push the client to a newer version. But for the clients that use installed software—such as mobile applications—to interact with the service, we often use rolling software updates, where the more recent version is gradually installed on the client-side. Therefore, data representation and data versioning are important concerns when designing an API.

This lesson discusses why data representation/formats matter and what considerations should be made when choosing suitable data format(s).

Representation considerations

From a general perspective, the information is communicated in the simplest form so that the recipient can comprehend it. Regarding API design, the goal is not as straightforward, but the choice of data representation is undoubtedly one of the main factors. Here are some points that must be considered when choosing a data format:

• Low latency: The user-perceived latency is one of the most common concerns when choosing a data format. API designers often prefer using data structures that facilitate fast network transfers. It may be part of an API SLA) to keep response time within certain limits. For example, to design APIs for time-critical applications such as live video conferencing, real-time surveillance systems, and so on, we may be unable to afford network delays.