The API Leach and the API Standard May 2, 2025

A few days ago, Einar W. Høst published a blog post, Socio-technical API patterns, in which he examines some socio-technical questions about APIs and describes a handful of recurring patterns in the interaction of APIs and the people designing, providing, and using these APIs. He calls these socio-technical API patterns. I quite liked the post. If you haven't done so, go read it! (I am also going to refer to some of his patterns later on, so I suggest reading his post before mine.)

In this post, I would like to add two patterns I have personally observed: the API Leach and the API Standard.

The API Leach

The API Leach is more of an anti-pattern. It comes about when a consumer is unable or unwilling to talk to the provider, but still needs the provided service. The consumer notices an interface exposed (but not advertised) by the provider and starts programming against it without the provider being aware of this. Maybe the interface is an internal API, or maybe it is not intended as an API at all, but as a UI for human users. Scraping web pages for data is one instance of this pattern.

Since the interface is not intended for consumption by external programs, the unwitting provider does not provide documentation, service levels, or support channels to the consumer team. The interface behavior is reverse engineered and may change at any time as the provider makes changes to the system. The interface may disappear without notice, too.

For the consumer team, this is a hard spot to be in. Reverse engineering an undocumented interface is inherently hard and error-prone, and once they are done, the team must be ready to deal with unexpected behavior (and failure) at any time – be it due to misunderstanding during the reverse engineering phase or to technical or functional changes. In all probability, they won't have a test environment, either, and need to test against the production interface with production data, which can severely limit the range of tests that are viable.

The provider team is mostly unaffected, but may notice some oddities:

These may cause the provider team to notice that something is up. And, of course, the producer may get yelled at after performing breaking changes if the consumer feels entitled enough.

Once the producer learns of the existence of the consumer, what happens next depends mostly on the power dynamics between the two parties. The interface may become an official API; the consumer may be shut out; both parties may negotiate a different API.

Another factor that determines the consequences is the intention of the consumer. The API Leach pattern is often used because the consumer is trying to accomplish something the producer would not be inclined to agree with – or at least has no incentive to support. In these situations, there may not be a good alternative, and if the leach is discovered, the provider will probably attempt to shut down the “integration”.

The pattern can also be established inadvertently, however, e.g., if the consumer fails to contact the producer due to lack of time or knowledge. In these cases, the situation can be resolved by establishing communication and explicitly agreeing on a different integration pattern.

It can also be the result of a team trying to put a Millstone on another team, but failing because they don't have the necessary clout. Sometimes, downstream failures due to changes by the unwilling provider can gather enough management attention to rectify the situation – or at least to make the Millstone possible after a period of leaching, which might be an improvement for the consumer, if not for the provider.

The API Standard

Using a documented API Standard is another pattern that extends beyond the merely technical considerations into the socio-technical domain. Using a standard decouples provider and consumer. The standard was designed for a particular purpose and is adopted by both provider and consumer, presumably because their needs align with this purpose. Collaboration on the API design is minimal because most of it is defined by the standard.

Most standards say little about operational aspects, however, so the service level offered by the provider most likely depends on other factors. Therefore, this pattern is usually combined with other patterns.

In conjunction with the Millstone, where a software team is forced to provide an API to the consumer without having an intrinsic motivation to do so, the API Standard alleviates the problem of coupling between the provider's internal data model and the API because the provider will typically have to implement some kind of mapping anyway. It is very unlikely that the internal model corresponds to the standard already. Thus, the Standard establishes a stable API contract that would be difficult to enforce otherwise. It does not solve the problem of "best effort" SLAs, though.

When combined with the Mountain, where the consumer is dependent on a provider with little to no influence on the API design and the API lifecycle, the Standard provides a measure of protection from the effects of the Volcano (the provider unilaterally deciding to discontinue – or massively alter – the API). If this happens, there will often be other providers using the same standard that can be moved to with little changes to the application code. If a data migration is necessary, the Standard may or may not be of help, depending on whether it specifies export/import functionality.

The Standard does probably not help with the Rapids, where an API is located in the middle of a value stream, but it may help with the Sock Puppet, where a team is talking to itself through an API. When a team manages multiple services, probably the requirements are not equally unique for all of them. There may well be services that perform standardized functions for which usage of a standardized API can reduce the cognitive load on the team and simplify onboarding for new team members.

A disadvantage of using an API Standard manifests if the needs of the consumer diverge from what the standard provides over time. In this case, you have the choice of forcing your needs into the corset of the standard (often suboptimal), augmenting the API with non-standard extensions (may work, but limits the usefulness of the standard), or ditching the standard altogether.

The API Leach may benefit from a provider that adheres to an API Standard (or maybe human interface guidelines), too, because this reduces the chances of breaking changes – although there is no guarantee that the provider will keep to the standard indefinitely – or even that the provider implements the standard correctly. Thus, the Standard does not solve the Leach's fundamental problem, but it may reduce the pain somewhat.

Conclusion

In this post, I wrote down two additional socio-technical API patterns. The API Leach describes the situation where a consumer taps into an “unofficial” interface of an unwitting provider. The API Standard describes how usage of an … API standard affects various other patterns.

If you have observed other patterns, I would appreciate it if you shared them.