apis posts - idmontie's Portfolio

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    img: "img",
    p: "p",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsxs(_components.p, {
      children: ["In 2008, Steve Ballmer once famously said “", _jsx(_components.a, {
        href: "https://www.youtube.com/watch?v=Vhh_GeBPOhs",
        children: "Developers, developers, developers"
      }), "” in a highly meme-able video. He was trying to emphasize the importance of software developers in business and that their importance was only going to continue to grow. Microsoft shifted to try to support software developers, noticing that if they supported developers, they would build better software for Windows, which in turn would make people want to use Windows."]
    }), "\n", _jsx(_components.p, {
      children: "The 2010s saw companies like “Twilio” have guiding questions like Jeff Lawson’s “Why Isn’t That and API?”. This guiding principle was based around the idea that if you build great APIs for software developers, they would want to use them, and in doing so, spend money on those services. For that entire decade, companies would start, build for engineers, and use the fly-wheel effect to become multi-billion dollar companies."
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2025-04-21-agents-agents-agents/why-isnt-that-an-api.png",
        alt: "Why isn't that an API?"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["Now, in the age of LLMs (Large Language Models) and AI, my assumption about the future is that we are going to find that “AI Agents” are the next Big Thing. We will probably see software engineers coding not to make APIs that other developers can use, but so that AI Agents can use. With ", _jsx(_components.a, {
        href: "https://openai.com/index/introducing-operator/",
        children: "OpenAI introducing Operator"
      }), ", their AI that can do tasks for you autonomously, the trajectory looks clear for companies that want to partner in this space: make products that will interface with AI Agents*."]
    }), "\n", _jsxs(_components.p, {
      children: ["And this isn’t going to only apply to software engineering. Even those in marketing are starting to think about how their content can be better consumed by the crawlers that feed into the training data for these LLMs. In “", _jsx(_components.a, {
        href: "https://benjamincongdon.me/blog/2025/01/25/AI-Slop-Suspicion-and-Writing-Back/",
        children: "AI Slop Suspicion and Writing Back"
      }), "”, the author hypothesizes about the future of SEO. Will we be writing not for other people to reach our content via search, but to see our content as part of an LLM’s answer to a question? If people are starting to transition to asking LLMs like ChatGPT a question first before they even Google, then wouldn’t getting your name and your thoughts ingested by the massive corpus of training data be beneficial in a sense, similar to a web-crawler indexing for search?"]
    }), "\n", _jsx(_components.p, {
      children: "These are questions I think we will see answered very soon, and some of the answers may not be ones we like. We may very well be starting to write content, apps, and APIs not for other people, but for machines."
    }), "\n", _jsx(_components.p, {
      children: "*Of course, not everyone is going to jump on this bandwagon. There are companies right now that make concerted efforts to make sure only humans use their site. They don’t have APIs, they stick their entire site behind a Cloudflare captcha check. These aren’t the companies I’m talking about as they weren’t trying to bridge into the larger software developer ecosystem."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


In 2008, Steve Ballmer once famously said “<a href="https://www.youtube.com/watch?v=Vhh_GeBPOhs">Developers, developers, developers</a>” in a highly meme-able video. He was trying to emphasize the importance of software developers in business and that their importance was only going to continue to grow. Microsoft shifted to try to support software developers, noticing that if they supported developers, they would build better software for Windows, which in turn would make people want to use Windows.
The 2010s saw companies like “Twilio” have guiding questions like Jeff Lawson’s “Why Isn’t That and API?”. This guiding principle was based around the idea that if you build great APIs for software developers, they would want to use them, and in doing so, spend money on those services. For that entire decade, companies would start, build for engineers, and use the fly-wheel effect to become multi-billion dollar companies.
<img alt="Why isn&#x27;t that an API?" src="/media/2025-04-21-agents-agents-agents/why-isnt-that-an-api.png" style="max-height:500px;margin:auto;text-align:center"/>
Now, in the age of LLMs (Large Language Models) and AI, my assumption about the future is that we are going to find that “AI Agents” are the next Big Thing. We will probably see software engineers coding not to make APIs that other developers can use, but so that AI Agents can use. With <a href="https://openai.com/index/introducing-operator/">OpenAI introducing Operator</a>, their AI that can do tasks for you autonomously, the trajectory looks clear for companies that want to partner in this space: make products that will interface with AI Agents*.
And this isn’t going to only apply to software engineering. Even those in marketing are starting to think about how their content can be better consumed by the crawlers that feed into the training data for these LLMs. In “<a href="https://benjamincongdon.me/blog/2025/01/25/AI-Slop-Suspicion-and-Writing-Back/">AI Slop Suspicion and Writing Back</a>”, the author hypothesizes about the future of SEO. Will we be writing not for other people to reach our content via search, but to see our content as part of an LLM’s answer to a question? If people are starting to transition to asking LLMs like ChatGPT a question first before they even Google, then wouldn’t getting your name and your thoughts ingested by the massive corpus of training data be beneficial in a sense, similar to a web-crawler indexing for search?
These are questions I think we will see answered very soon, and some of the answers may not be ones we like. We may very well be starting to write content, apps, and APIs not for other people, but for machines.
*Of course, not everyone is going to jump on this bandwagon. There are companies right now that make concerted efforts to make sure only humans use their site. They don’t have APIs, they stick their entire site behind a Cloudflare captcha check. These aren’t the companies I’m talking about as they weren’t trying to bridge into the larger software developer ecosystem.


In 2008, Steve Ballmer once famously said “[Developers, developers, developers](https://www.youtube.com/watch?v=Vhh_GeBPOhs)” in a highly meme-able video. He was trying to emphasize the importance of software developers in business and that their importance was only going to continue to grow. Microsoft shifted to try to support software developers, noticing that if they supported developers, they would build better software for Windows, which in turn would make people want to use Windows.

The 2010s saw companies like “Twilio” have guiding questions like Jeff Lawson’s “Why Isn’t That and API?”. This guiding principle was based around the idea that if you build great APIs for software developers, they would want to use them, and in doing so, spend money on those services. For that entire decade, companies would start, build for engineers, and use the fly-wheel effect to become multi-billion dollar companies.

![Why isn't that an API?](/media/2025-04-21-agents-agents-agents/why-isnt-that-an-api.png)

Now, in the age of LLMs (Large Language Models) and AI, my assumption about the future is that we are going to find that “AI Agents” are the next Big Thing. We will probably see software engineers coding not to make APIs that other developers can use, but so that AI Agents can use. With [OpenAI introducing Operator](https://openai.com/index/introducing-operator/), their AI that can do tasks for you autonomously, the trajectory looks clear for companies that want to partner in this space: make products that will interface with AI Agents*.

And this isn’t going to only apply to software engineering. Even those in marketing are starting to think about how their content can be better consumed by the crawlers that feed into the training data for these LLMs. In “[AI Slop Suspicion and Writing Back](https://benjamincongdon.me/blog/2025/01/25/AI-Slop-Suspicion-and-Writing-Back/)”, the author hypothesizes about the future of SEO. Will we be writing not for other people to reach our content via search, but to see our content as part of an LLM’s answer to a question? If people are starting to transition to asking LLMs like ChatGPT a question first before they even Google, then wouldn’t getting your name and your thoughts ingested by the massive corpus of training data be beneficial in a sense, similar to a web-crawler indexing for search?

These are questions I think we will see answered very soon, and some of the answers may not be ones we like. We may very well be starting to write content, apps, and APIs not for other people, but for machines.

*Of course, not everyone is going to jump on this bandwagon. There are companies right now that make concerted efforts to make sure only humans use their site. They don’t have APIs, they stick their entire site behind a Cloudflare captcha check. These aren’t the companies I’m talking about as they weren’t trying to bridge into the larger software developer ecosystem.


Agents, Agents, Agents

Maintaining growing software is challenging. Poorly architected APIs and
incorrect abstractions can significantly impact the ability for engineering
teams to deliver new features in a timely manner. If we consider an
API's complixty as being a significant contributor to its overhead,
maintainability, and ease of use, then it becomes a question of how
do we best measure this complexity so that we can make informed decisions
about how to refactor and improve our APIs.



We will consider an API as an abstract set of functions, each with a
defined set of input parameters and outputs. An API can represent a library,
an interface, or a set of functions in a design system.

## An API as a Surface

A good API minimizes the complexity that a consumer needs to understand
in order to use it. If we think of an API as an abstract two dimensional
surface, then the complexity of the internals of the API - all the code
that is required to implement the API - is the area of that surface.
The API that is exposed as functions, input parameters, and outputs is
the perimeter of that surface. This follows from the conscept that an
API should act as a "black box" - the consumer should not need to know
how the API is implemented in order to use it.

From this metaphor, we can also think of the "best" API as one that
minimizes the perimeter of the surface while maximizing the necessary
area of the surface.

## The Complexity of a Surface

The percieved complexity of an API can be influenced by the number of functions,
the numbner of parameters, and the number of return values.

We will not be considering the internal state of the services that consumers
may need to manage. Instead, we will focus on "idempotent" functions - those
that do not have side effects and do not require any state to be managed.

Abstractly, we can denote the API Surface $S$ as a set of functions $f_i$,
where the complexity of each function $f_i$ is given by $c(f_i)$, and the
overall complexity of the surface is given by:

$$
C(S) = \sum_{i=1}^{n} c(f_i)
$$

where $n$ is the number of functions in the surface.

As we increase the number of functions in the surface, the complexity of the
surface is also expected to increase.

## The Complexity of a Function

The complexity of a function $f_i$ can be influenced by the number of input
parameters, their values, and the number of return values.

Take for example a function $f(x: boolean): boolean$ that takes a single
boolean input and returns a boolean value. The complexity of this function
is relatively low - there are only two possible input values and two possible
output values.

If we jump to a function $f(x: boolean, y: boolean, z: boolean): boolean$
then the complexity of this function is higher - there are now $2^3 = 8$
possible input values and two possible output values.

As we increase the number of input parameters, we increase the number
of combinations of input values that the function can accept. This
increases the complexity of the function:

$$
c(f_i) = \prod_{p} |p| + |r|
$$

where $p$ is the set of input parameters, $r$ is the set of return values,
and $|p|$ is size of the set of input parameters and $|r|$ is the size of
the set of return values. By "size" we mean the number of "meaningful"
values that a parameter type has. For example, a boolean has two meaningful values,
but an integer may have an infinite range of non-meaningful values. In some
languages, like C, it is common for an integer to have meaningful values
of -1 and 0, and non-meaningful values of all other integers. In the case where
the integer is simply a number, we would consider the size of the parameter
to be 1, while the size of a C-like integer to be the number of "special" cases
the integer has.

Aaron Luu, in his article [Don't use boolean](https://www.luu.io/posts/dont-use-booleans)
alludes to this exponential potential for complexity when using boolean
values.

## Tests as Consumers

Interestingly, the tests for an API already act as a consumer and can demonstrate
the complexity of an API as it stives to cover all possible branches and use-cases.
For our function with 3 boolean inputs, we would need to write 8 tests to cover
all possible input combinations. A suite of tests that check tons of combinations
of inputs and outputs is a good indicator that the API is complex.

## Techniques for Reducing Complexity

This is by no means an exhaustive list, but here are some techniques that
can help reduce complexity.

First is to identify if the parameters are truly independent. For example, let's take
the example:

```
f(x: boolean, y: Data | undefined): boolean
```

If the value of $y$ is only meaningful when $x$ is true, then we can consider
$y$ to be a dependent parameter. If we write out a matrix of possible inputs:

- x: true, y: Data
- x: false, y: Data
- x: true, y: undefined
- x: false, y: undefined

We can see that the value of $y$ is only meaningful when $x$ is true.

When we have dependent parameters, we can consider using the type-system to
help us manage the complexity. For example, we could just simplify the
function to allow only valid inputs:

```
f(x: Data | false): boolean
```

Depending on the values of Data, this simplifies the complexity of the function by
half.

Another technique is to consider reducing boolean inputs to a single enum-like
input type. For example, simplifying 3 boolean parameters into a single
enum-like parameter:

```
f(x: 'all' | 'none' | 'some'): boolean
```

This reduces the number of possible input combinations from 8 to 3.

## Conclusion

This is one simple way to measure the complexity of an API, which shows
that the bigger the surface area, the more complex the API. The majority
of this complexity comes from thee combinations of input parameters and
return values. By reducing the number of input parameters and return values,
we can reduce the complexity of the API.

This is by no means the only way to measure the complexity of an API, but
it is a useful way to think about the complexity of an API in terms of
the number of possible input and output combinations.

Agents, Agents, Agents

APIs, Complexity, and Surfaces