
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 o fan  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,
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 test 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.

APIs, Complexity, and Surfaces

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    h2: "h2",
    img: "img",
    li: "li",
    ol: "ol",
    p: "p",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "Every system has its limits. When designing and architecting systems, sometimes we as engineers like to assume things can scale infinitely. Maybe we can use larger machines, or maybe we can deploy more instances of a service. But even trying to scale systems isn’t magically infinite. It’s a smart move to understand the limitations of what we are building upfront so we can make better technology choices, and squeeze the performance out of our existing systems."
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2023-12-08-the-breaking-point/splash.png",
        alt: "The Breaking Point"
      })
    }), "\n", _jsx(_components.h2, {
      children: "The Myth of Scaling"
    }), "\n", _jsx(_components.p, {
      children: "Software engineering often has an optimistic mindset that scaling a service is easy: we just let the more instances of the service be deployed, and viola, perfect scaling! But the reality is a bit more complex. Instances don't always fire up instantly, services can fail unexpectedly, and not every component can scale indefinitely."
    }), "\n", _jsx(_components.p, {
      children: "That’s why it’s important to understand the limitations of our services. Knowing where the system might buckle under pressure allows us to devise strategies to prevent these breaking points from turning into disasters."
    }), "\n", _jsx(_components.p, {
      children: "For example, we may have a public API service with set auto-scaling rules. When the service is hit with many requests, the service spawns additional instances to handle the workload. This ends up working well in most cases, but in the real-world, the service ends up getting hit with huge bursts of requests from downstream users, rather than a steady increase of traffic. When this happens, we scale the service instances up, but now the database gets hit with too many writes and fails over, since the database was originally designed as a read heavy use-case. Of course this is a contrived example, but similar edge-cases commonly appear in complex architectures."
    }), "\n", _jsx(_components.p, {
      children: "Without understanding the full system and the constraints of each part, it can be difficult to successfully scale."
    }), "\n", _jsx(_components.h2, {
      children: "Understanding Server Limitations"
    }), "\n", _jsx(_components.p, {
      children: "A good starting point for finding your system’s breaking point is to see how it fares on a single machine. Profile the memory usage when under load, and use load testing to determine how many simultaneous requests the service can handle before performance degrades. To make sense of it all, set some benchmarks:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Determine what it means for performance to degrade. In some systems, you may have SLAs for some percentage of requests to complete within a given response time. Other systems may have more leniency."
      }), "\n", _jsx(_components.li, {
        children: "Use readily available tools to bombard your service with requests and observe the results. For web API services, there are plenty of open source tools that can sustain issuing millions of requests a second and reporting results."
      }), "\n", _jsx(_components.li, {
        children: "Run the tests multiple times and throw out any outliers in the results. From the rest, understand the peak memory usage, peak disk usage, and peak CPU usage of the service."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Once you have the information from these types of load tests, it becomes easy to identify indicators that a service will begin to degrade. For some services it is CPU usage that will increase more than the other resources. For some services, memory can get exhausted first."
    }), "\n", _jsx(_components.p, {
      children: "The load testing will also be a good indicator of how many requests a single instance of your service can handle before falling over."
    }), "\n", _jsx(_components.h2, {
      children: "Scaling Strategies"
    }), "\n", _jsx(_components.p, {
      children: "When dealing with monolithic services or hefty microservices, you may find from load testing that just vertically scaling the service by adding more hardware is more cost efficient than replicating the instance."
    }), "\n", _jsx(_components.p, {
      children: "Fore smaller service that use less memory and CPU footprint, it may make more sense to horizontally scale the service with many additional smaller servers being deployed."
    }), "\n", _jsx(_components.p, {
      children: "Cloud services like AWS, Azure, and GCP help enable either decision. With AWS, there are many different instance types to get the right size for your specific service deployment. With the right size picked out, auto-scaling becomes a more budget-friendly option, as you're only spinning up instances that meet your specific resource requirements."
    }), "\n", _jsx(_components.p, {
      children: "Cloud providers additionally have ways to detect when to auto-scale an instance based on resource usage, making load testing very informative to tune these values."
    }), "\n", _jsx(_components.h2, {
      children: "Conclusion"
    }), "\n", _jsx(_components.p, {
      children: "Scaling isn’t a one-size-fits-all solution. It’s about understanding the unique limitations and potential of your system. Through careful analysis, load testing, and a bit of strategic thinking, you can develop a scaling strategy that not only meets your performance needs but also keeps an eye on the cost of your system. Whether it’s beefing up your hardware or multiplying smaller instances, the key lies in making informed, tailored decisions for your system's specific demands and quirks."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>Every system has its limits. When designing and architecting systems, sometimes we as engineers like to assume things can scale infinitely. Maybe we can use larger machines, or maybe we can deploy more instances of a service. But even trying to scale systems isn’t magically infinite. It’s a smart move to understand the limitations of what we are building upfront so we can make better technology choices, and squeeze the performance out of our existing systems.</p>
<p><img alt="The Breaking Point" src="/media/2023-12-08-the-breaking-point/splash.png" style="max-height:500px;margin:auto;text-align:center"/></p>
<h2>The Myth of Scaling</h2>
<p>Software engineering often has an optimistic mindset that scaling a service is easy: we just let the more instances of the service be deployed, and viola, perfect scaling! But the reality is a bit more complex. Instances don&#x27;t always fire up instantly, services can fail unexpectedly, and not every component can scale indefinitely.</p>
<p>That’s why it’s important to understand the limitations of our services. Knowing where the system might buckle under pressure allows us to devise strategies to prevent these breaking points from turning into disasters.</p>
<p>For example, we may have a public API service with set auto-scaling rules. When the service is hit with many requests, the service spawns additional instances to handle the workload. This ends up working well in most cases, but in the real-world, the service ends up getting hit with huge bursts of requests from downstream users, rather than a steady increase of traffic. When this happens, we scale the service instances up, but now the database gets hit with too many writes and fails over, since the database was originally designed as a read heavy use-case. Of course this is a contrived example, but similar edge-cases commonly appear in complex architectures.</p>
<p>Without understanding the full system and the constraints of each part, it can be difficult to successfully scale.</p>
<h2>Understanding Server Limitations</h2>
<p>A good starting point for finding your system’s breaking point is to see how it fares on a single machine. Profile the memory usage when under load, and use load testing to determine how many simultaneous requests the service can handle before performance degrades. To make sense of it all, set some benchmarks:</p>
<ol>
<li>Determine what it means for performance to degrade. In some systems, you may have SLAs for some percentage of requests to complete within a given response time. Other systems may have more leniency.</li>
<li>Use readily available tools to bombard your service with requests and observe the results. For web API services, there are plenty of open source tools that can sustain issuing millions of requests a second and reporting results.</li>
<li>Run the tests multiple times and throw out any outliers in the results. From the rest, understand the peak memory usage, peak disk usage, and peak CPU usage of the service.</li>
</ol>
<p>Once you have the information from these types of load tests, it becomes easy to identify indicators that a service will begin to degrade. For some services it is CPU usage that will increase more than the other resources. For some services, memory can get exhausted first.</p>
<p>The load testing will also be a good indicator of how many requests a single instance of your service can handle before falling over.</p>
<h2>Scaling Strategies</h2>
<p>When dealing with monolithic services or hefty microservices, you may find from load testing that just vertically scaling the service by adding more hardware is more cost efficient than replicating the instance.</p>
<p>Fore smaller service that use less memory and CPU footprint, it may make more sense to horizontally scale the service with many additional smaller servers being deployed.</p>
<p>Cloud services like AWS, Azure, and GCP help enable either decision. With AWS, there are many different instance types to get the right size for your specific service deployment. With the right size picked out, auto-scaling becomes a more budget-friendly option, as you&#x27;re only spinning up instances that meet your specific resource requirements.</p>
<p>Cloud providers additionally have ways to detect when to auto-scale an instance based on resource usage, making load testing very informative to tune these values.</p>
<h2>Conclusion</h2>
<p>Scaling isn’t a one-size-fits-all solution. It’s about understanding the unique limitations and potential of your system. Through careful analysis, load testing, and a bit of strategic thinking, you can develop a scaling strategy that not only meets your performance needs but also keeps an eye on the cost of your system. Whether it’s beefing up your hardware or multiplying smaller instances, the key lies in making informed, tailored decisions for your system&#x27;s specific demands and quirks.</p>


Every system has its limits. When designing and architecting systems, sometimes we as engineers like to assume things can scale infinitely. Maybe we can use larger machines, or maybe we can deploy more instances of a service. But even trying to scale systems isn’t magically infinite. It’s a smart move to understand the limitations of what we are building upfront so we can make better technology choices, and squeeze the performance out of our existing systems.

![The Breaking Point](/media/2023-12-08-the-breaking-point/splash.png)

## The Myth of Scaling

Software engineering often has an optimistic mindset that scaling a service is easy: we just let the more instances of the service be deployed, and viola, perfect scaling! But the reality is a bit more complex. Instances don't always fire up instantly, services can fail unexpectedly, and not every component can scale indefinitely.

That’s why it’s important to understand the limitations of our services. Knowing where the system might buckle under pressure allows us to devise strategies to prevent these breaking points from turning into disasters.

For example, we may have a public API service with set auto-scaling rules. When the service is hit with many requests, the service spawns additional instances to handle the workload. This ends up working well in most cases, but in the real-world, the service ends up getting hit with huge bursts of requests from downstream users, rather than a steady increase of traffic. When this happens, we scale the service instances up, but now the database gets hit with too many writes and fails over, since the database was originally designed as a read heavy use-case. Of course this is a contrived example, but similar edge-cases commonly appear in complex architectures.

Without understanding the full system and the constraints of each part, it can be difficult to successfully scale.

## Understanding Server Limitations

A good starting point for finding your system’s breaking point is to see how it fares on a single machine. Profile the memory usage when under load, and use load testing to determine how many simultaneous requests the service can handle before performance degrades. To make sense of it all, set some benchmarks:

1. Determine what it means for performance to degrade. In some systems, you may have SLAs for some percentage of requests to complete within a given response time. Other systems may have more leniency.
2. Use readily available tools to bombard your service with requests and observe the results. For web API services, there are plenty of open source tools that can sustain issuing millions of requests a second and reporting results.
3. Run the tests multiple times and throw out any outliers in the results. From the rest, understand the peak memory usage, peak disk usage, and peak CPU usage of the service.

Once you have the information from these types of load tests, it becomes easy to identify indicators that a service will begin to degrade. For some services it is CPU usage that will increase more than the other resources. For some services, memory can get exhausted first.

The load testing will also be a good indicator of how many requests a single instance of your service can handle before falling over.

## Scaling Strategies

When dealing with monolithic services or hefty microservices, you may find from load testing that just vertically scaling the service by adding more hardware is more cost efficient than replicating the instance.

Fore smaller service that use less memory and CPU footprint, it may make more sense to horizontally scale the service with many additional smaller servers being deployed.

Cloud services like AWS, Azure, and GCP help enable either decision. With AWS, there are many different instance types to get the right size for your specific service deployment. With the right size picked out, auto-scaling becomes a more budget-friendly option, as you're only spinning up instances that meet your specific resource requirements.

Cloud providers additionally have ways to detect when to auto-scale an instance based on resource usage, making load testing very informative to tune these values.

## Conclusion

Scaling isn’t a one-size-fits-all solution. It’s about understanding the unique limitations and potential of your system. Through careful analysis, load testing, and a bit of strategic thinking, you can develop a scaling strategy that not only meets your performance needs but also keeps an eye on the cost of your system. Whether it’s beefing up your hardware or multiplying smaller instances, the key lies in making informed, tailored decisions for your system's specific demands and quirks.


The Breaking Point - Understanding the performance of your systems

"use strict";
const {jsx: _jsx} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    p: "p",
    ...props.components
  };
  return _jsx(_components.p, {
    children: "Dive into the dynamic world of the WAX blockchain with this comprehensive tutorial series. From creating unique non-fungible tokens (NFTs) using AtomicAssets and crafting simple \"Hello World\" contracts, to deploying intricate guestbook contracts both locally and on the testnet, these tutorials provide a step-by-step guide to harnessing the full potential of WAX. Whether you're a developer eager to explore decentralized applications or an enthusiast curious about digital assets, this series offers invaluable insights into the robust capabilities of the WAX platform."
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>Dive into the dynamic world of the WAX blockchain with this comprehensive tutorial series. From creating unique non-fungible tokens (NFTs) using AtomicAssets and crafting simple &quot;Hello World&quot; contracts, to deploying intricate guestbook contracts both locally and on the testnet, these tutorials provide a step-by-step guide to harnessing the full potential of WAX. Whether you&#x27;re a developer eager to explore decentralized applications or an enthusiast curious about digital assets, this series offers invaluable insights into the robust capabilities of the WAX platform.</p>


Dive into the dynamic world of the WAX blockchain with this comprehensive tutorial series. From creating unique non-fungible tokens (NFTs) using AtomicAssets and crafting simple "Hello World" contracts, to deploying intricate guestbook contracts both locally and on the testnet, these tutorials provide a step-by-step guide to harnessing the full potential of WAX. Whether you're a developer eager to explore decentralized applications or an enthusiast curious about digital assets, this series offers invaluable insights into the robust capabilities of the WAX platform.

My e-book on WAX Smart Contract development that guides developers through the process of creating a non-fungible token (NFT) smart contract.


Interactive Smart Contracts on WAX

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    p: "p",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "This is a 22 part series on DevTo that goes through the entire process of creating\na WAX Smart Contract that interacts with AtomicAssets and the WAX RNG Oracle."
    }), "\n", _jsx(_components.p, {
      children: "It is a great introduction to WAX smart contract development and the WAX ecosystem."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>This is a 22 part series on DevTo that goes through the entire process of creating
a WAX Smart Contract that interacts with AtomicAssets and the WAX RNG Oracle.</p>
<p>It is a great introduction to WAX smart contract development and the WAX ecosystem.</p>


This is a 22 part series on DevTo that goes through the entire process of creating
a WAX Smart Contract that interacts with AtomicAssets and the WAX RNG Oracle.

It is a great introduction to WAX smart contract development and the WAX ecosystem.


WAX smart contract development course that guides developers through the process of creating a non-fungible token (NFT) smart contract.


Welcome

Latest Posts

APIs, Complexity, and Surfaces

The Breaking Point - Understanding the performance of your systems

Latest Projects

Interactive Smart Contracts on WAX

WAX C++ NFT Tutorial