Stay Connected and Keep Current

History of APIs

From the very first time that one system needed to talk to another system, APIs have been with us. In the early days, APIs were complex, cryptic, and a little mysterious; even the meaning of the acronym – application programming interface – can be a little intimidating, a little overwhelming. The purpose of an API is to let two systems interact. Historically, the messages that were exchanged made sense only when interpreted with the special “magic decoder ring” that system programmers created and maintained.

APIs have emerged from the depths of system-to-system communications, and are now part of what organizations reveal to the world. No longer deep, dark secrets, APIs are seeing the light. APIs are products. Companies realize the value in producing not just end-to-end solutions, but component solutions that can be integrated together by others, using the APIs.  And, as APIs emerge into the light, APIs are becoming human readable.

Human readability is a big part of why an API might be adopted. APIs are the doorway to the capabilities that will be realized, but if the doorway is not inviting, potential consumers of the API may never realize those capabilities. Creating human-readable APIs continues to evolve, and will, I believe, forever be a mix of both science and art. There’s no recipe that will consistently create a good API, and even defining what “good” means is difficult. Like the answer about what is good art, I will know a good API when I see one.

So what can contribute to creating a human-readable? I believe the following are important:

Time:

API requests and responses are a new type of user interface.  We typically devote significant amounts of time to build visually appealing and functionally useful web pages, and that same level of planning must be applied when creating APIs.

Taking the time to gather feedback about usability has tremendous value.  We must think about the developer – will a developer see our APIs, be attracted to them, want to learn how to interact with them, and ultimately integrate them into their solutions? Just as we focus on user experience (UX) for our web pages, we must focus on developer experience (DX) for our APIs. Both take time.

Structure:

APIs provide information, and it is important that the information is modeled in a way that makes sense. This often means stepping back from the world that we know well and thinking about how that world might be seen by others.

Avoid the deeply intertwined data models with extensive cross-referencing, and present the message in a relatively flat model. Allow the user of the API to quickly access individual data elements, without the need to reassemble the needed information from a collection of different locations throughout the message. Try to avoid data structures where some elements are used for one scenario, and others are used for another scenario. Group related elements so that the parent element may be optional, but if provided, all child elements are mandatory.

JSON messages are considerably easier for humans to read. The message structure is managed using simple characters (braces, square brackets, and commas) and the data that is the purpose for the message is not lost within the noise of other words, as is common with XML.

Words:

Finding the correct word or phrase can be difficult, especially when we are immersed in an industry where certain words and phrases have become engrained in our DNA. Very often, when others hear us talk using words and phrases that are common to our business area, we don’t understand why they are confused. In travel, we talk about “selling air.” To an outsider, that sounds as lucrative a business as living on the coast and selling sea water!

 We create car APIs, but those APIs allow rentals of trucks. Would an API labeled as a hotel API suggest that it can support the reservation of a Yurt for a few nights? Within the travel world we talk about legs (aren’t those body parts?) and segments (aren’t those pieces of an orange?) and how does one even attempt to explain “open jaw”? Words are very powerful, and we must work hard to use the ones that are relevant, understandable and appropriate.

Consistency:

Settle on something and be consistent with that, throughout the individual API and across all related APIs. If one API refers to a “confirmation number” then don’t use “confirmation id” in another place. If you use “number of days” then don’t use “passenger count” – use “number of passengers”. Consistency can be harder to achieve when there is a team that is defining the API. The intent is to deliver something that has the appearance of one author, and style guides play a crucial role in achieving this. Note that consistency does not mean perfection, but it does mean a uniformity, a uniformity that can always be advanced across the suite of APIs.

Creating human-readable API messages is a craft, and like any craft, improvement comes with practice and training. Devote the time that is needed, learn from others and make the APIs understandable and engaging. Be open to feedback – and have fun as you build your APIs.  Throw away that magic decoder ring if you still have it. The APIs of today are human-readable – now go read one!