Just like physics has its laws, tech is full of its own theories. Behind many architectural decisions in software development, there’s often a “law” or “rule” used as a rationale. This is no less true concerning APIs and microservices. Today, we’ll look at some of these rules and consider their relevance in modern API-first development.

Gall’s Law

Gall’s Law is a principle related to systems design that was created by famed pediatrician John Gall. After spending most of his career in childhood behavioral and developmental research, Gall collected this research into a book called General Systematics. Based on his observations on childhood issues, he formed a theory that they were generally caused by systems that did not adequately address the root cause of the problem. This led to his stated law:

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.

The core takeaway from Gall’s Law is that large systems cannot be created in their perfect and final form. They must instead be iterated from simple systems that accomplish a smaller subset of the final set of tasks.

Examples

One example of Gall’s Law in software development is found in Apache Thrift. Thrift allows developers to create a definition file that contains data types and service interfaces. This definition serves as a sort of Rosetta Stone between languages, helping to form a communication interchange and defined pattern of use that is then used by the Thrift compiler to create code. This code can then be used to create servers, clients, etc., to facilitate scalability across languages, regardless of how complex and different those languages might be compared to one another.

Conway’s Law

Conway’s Law, created by programmer and computer scientist Melvin Conway, is a law that suggests the core nature of a developmental organization is reflected within the product it creates. The law reads deceptively simple, but its impact is extremely wide-reaching.

Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.

The rule has been shown to be relevant across various fields, from medical to educational, but is especially relevant in software development. It should be noted that the organizational reflection is not just true in terms of the corporate and team structure, but is also true in relation to company culture, communication paradigms, and the dynamics of inter-team communication.

Examples

Conway’s Law is a well-researched topic, and as such, there is quite a bit of academic evidence. In a 2012 paper entitled “Exploring the Duality Between Product and Organizational Architectures: A Test of the ‘mirroring’ Hypothesis” by Alan MacCormack, Carliss Baldwin, and John Rusnack, a research team compiled a list of systems developed by providers, both open source and closed source, to see whether or not the organizational structures of the groups behind the software were reflected in the developed solution.

Through a broad comparison of the organizational structures and the resulting coupling of the resulting systems, the researchers found a strong correlation across the tested entities, concluding:

We find strong evidence to support the hypothesis that a product’s architecture tends to mirror the structure of the organization in which it is developed. In all the pairs we examine, the loosely-coupled organization develops a product with a more modular design than that of the tightly-coupled organization.

The Bezos API Mandate

The Bezos Mandate is one of the best-known “laws” specific to the API space. With its original source lost to time and internet decay, the mandate was apparently issued in 2002 by Amazon founder Jeff Bezos. It should be noted that, as with many things attributed to individual minds, this mandate was likely the result of ideation from many stakeholders at Amazon at the time. The mandate read as follows:

1. All teams will henceforth expose their data and functionality through service interfaces.
2. Teams must communicate with each other through these interfaces.
3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.
4. It doesn’t matter what technology they use. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.
5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.
6. Anyone who doesn’t do this will be fired.
7. Thank you; have a nice day!

This mandate has a few important aspects to it. First, it sets the expectation that all data and functionality should be surfaced not through individual builds or limited gateways, but through interfaces, resulting in a huge boost to transparency and standardization. This approach decreased tight-coupling and the siloing of teams that was commonplace in other corporate entities of the time, creating extreme potential upside that would ultimately build Amazon into what it is today.

Examples

One only has to look at Amazon to see the benefits of designing internal services for externalization. Following this philosophy, Amazon has grown from a small book retailer to a massive eCommerce and software infrastructure juggernaut. While AWS existed in an early form as far back as 2000, it wasn’t until 2002 that the system would be opened up to developers. When this happened, developers took to the system broadly, creating a massive amount of applications using the service.

This interest would ultimately lead to the internal conceptualization of an “Internet OS” by Andy Jassy in which the constituent parts of a software development process would be provided by Amazon, surfacing the internal structures, systems, and approaches to all. By 2003, Amazon had added database, computation, and storage systems. Today, these systems are ubiquitous, serving massive amounts of data across the web.

Hyrum’s Law

So far, we’ve discussed laws principally concerned with internal practices. On the other hand, Hyrum’s Law considers user behavior once a service is public and usable. Hyrum’s Law is named after Google engineer Hyrum Wright, who stated:

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.

What this means in practice is that it doesn’t really matter what you intended your system to do or what functionality is explicitly documented in the release. If the service performs a certain way, with enough users, someone will rely on it. This applies to undocumented functions, response formatting, and even bugs or anticipated performance bottlenecks. This nature of developers to build using whatever is available is known as the implicit interface.

Examples

Suppose an API outputs a timestamp in an undocumented custom format, but one day the software providers decide to standardize it to ISO 8601. API consumers have relied upon the old behavior and added data transformations on their end, which break with the new format. Or, suppose an API orders its responses based on the date the queried resources were last modified. If this is changed to be ordered by the number of interactions by other users, this can result in the integrations built against the system breaking.

Murphy’s Law

Murphy’s Law is a simple adage — “anything that can go wrong will go wrong.” In the context of API design, this typically means that developers should develop for both the ideal use case and the extreme edge case where everything goes wrong.

This might seem like a paranoid approach, but the reality is that the user, their environment, and other conditions can be very hard to predict. Creating an API that relies on a steady internet connection or only assumes a specific kind of interaction from the user can result in a system that cannot handle on-the-ground realities.

Example

Let’s assume you have a media API that utilizes a check on another API to provide contextual data to a user. When a user requests information about a media file, the API first has to reach out to another internal API to validate the title of the queried object to validate the entry. What happens when the object being queried uses characters that are not allowed and are not escaped from the output? How will the API handle something being returned with characters that are interpreted as commands, end-of-entry markers, etc.? Without planning for such a use case, a user may break the API by querying an obscure album or song title that happens to have illegal characters.

Conclusion

These rules aren’t necessarily hard and fast. As with most things in technology, the exact circumstances will dictate your approach, and there are sometimes exceptions to these rules. Generally speaking, however, each of these principles is worth considering.

And, of course, there are plenty of other more general “laws” in tech, like the platform network effect, The Pareto Principle (often called the 80/20 rule), and API-first. Each of these has come to direct architectural designs and inspire new business models.

What rules do you see being discussed in the context of APIs? Have we missed any? Let us know in the comments below!