Keep Your API Simple: The Road to Efficiency and Ease of Use
An API is the entry point to a tool, so keeping its complexity under control matters. When your business depends on API services, simplicity can become a competitive edge.
When picking a tool, we should weigh what it costs against how well it serves our needs. It has to do the job we expect and do it well. Sometimes, if two tools are equally capable, the simpler one is the better choice because it saves time. An API is the entry point to a tool, so keeping its complexity under control matters. When your business depends on API services, simplicity can become a competitive edge.
This article discusses how complication leads to trouble in APIs. We’ll examine what can make an API more complicated, including what it has to do and how it is designed. Reading it will help you:
- Steer clear of unnecessary complication.
- Identify the sources of complication.
- Simplify existing solutions and make them more efficient.
What is Complication
First, we need to pin down what complication actually means. The dictionary defines complication as:
a thing that makes a situation harder, or the act of making it so
For APIs, this covers anything that makes an API harder to use or to build.
Keep in mind that “complication” and “complexity” are frequently treated as synonyms, although their meanings differ a little. Looking up complexity in the dictionary, we find that it refers to:
the condition of consisting of many parts and being hard to understand or solve
With APIs, complexity may relate to the structure (for example the number of endpoints, headers, and attributes in the message body) or to the system concealed behind the API (such as the number of modules or microservices). Complexity is certainly one of the things that can lead to complication.
Because of this difference, the rest of this article will mostly talk about “complication” rather than “complexity.” I chose this term to emphasize the particular challenges and difficulties that can emerge when designing and using APIs.
Problems of an Over-complicated API
Many problems can stem from complication in an API. The most frequent ones are:
| From the API integrator’s point of view | From the API provider’s point of view |
| Integrations often fail | Testing is troublesome |
| Lots of time spent going through documentation | Monitoring is hard |
| A high volume of requests to the API support team | Scaling is hard |
| Integrations take a long time | A lot of time goes into handling integrators’ requests |
| Maintenance requires a lot of effort | New features take a long time to deliver |
| Maintenance requires a lot of effort |
When you notice any of these symptoms, it’s essential to find out what is behind them and check whether they come from API complication. If they do, take a moment to think about how your API got so convoluted. That reflection is the key to removing the root cause of the problem or at least effectively limiting its impact.
The following sections look at the factors that affect API complication.
Factors of API complication
There are so many things that can make an API complicated that listing and describing all of them in one article would be practically impossible. Nearly all of them, though, fall into one of these groups:
- Functional Requirements: Everything expected in terms of the functionalities offered.
- Non-functional Requirements: Everything expected in terms of performance, reliability, security, and other quality attributes.
- Poor API structure: A less-than-ideal design and arrangement of the API’s components, endpoints, and interactions.
Next, we’ll go through each of these groups, highlighting their particular challenges and the considerations that come with them.
Functionalities provided by API
An API exists mainly to expose functionalities that integrators can use. Yet as more and more features are added, the API may grow more complicated. That’s why choosing which functions go into the API deserves real care. Typically, the decision is driven by what clients ask for most, but other aspects can be taken into account too, such as how well a feature aligns with the API provider’s business strategy.
To make this clearer, let’s take a bookstore API as an example. Here we expose an endpoint returning the available books with prices in a currency the API client picks via this query parameter:
GET /book-store-api/books?price.currency=USD
{
"books": [
{
"id": "04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets to writing pristine,
maintainable, and efficient code that stands the test of time.
Discover essential principles, patterns, and best
practices that empower you to create software that is
not only functional but also a joy to read and work with.
Take your programming skills to the next level
with this indispensable guide to achieving clarity,
simplicity, and excellence in your code."
},
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide to mastering
the art of pragmatic software development. Learn how
to approach coding challenges with a practical
mindset, leverage powerful tools, and adopt
efficient techniques that lead to success in
any programming project. Unravel the secrets
of effective team collaboration, debugging,
and problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world advice,
this book is your roadmap to becoming
a truly pragmatic programmer."
}
]
}
Letting the client choose the price currency adds complication here and brings the following challenges:
- Currency Fluctuations: Because book prices depend on exchange rates, they may be unstable, which could mean customers see inconsistent prices.
- Refund Policy Complexity: A refund policy for purchases in different currencies can get complicated, since the amount refunded may change along with exchange rates.
- Exchange Rate Mechanism: Something has to fetch and manage exchange rates so that currency conversions are correct.
- Handling Failures: Errors when fetching exchange rates must be handled gracefully so the service isn’t disrupted.
All of these challenges can be dealt with, but it’s important to think carefully about whether the business value of offering the API in several currencies justifies the costs and difficulties listed above.
The lesson here is to be cautious when deciding which features to build. Every new functionality comes at a price, and that price frequently goes beyond the cost of implementing it. Careful thought is needed to find the right balance between delivering value and keeping an API’s complexity in check.
Non-Functional requirements
Non-functional requirements concern the general properties of a system that aren’t tied directly to a particular domain. In “Fundamentals of Software Architecture” by Mark Richards and Neal Ford, they are called Architecture Characteristics and described like this:
the significant aspects of a system that do not depend on the problem domain
The authors also stress that these requirements should be kept to a minimum rather than piled on:
An application could provide an enormous number of architecture characteristics – but it shouldn’t. Every architecture characteristic it supports makes the design more complex. That is why one of an architect’s key responsibilities is to select as few architecture characteristics as possible, not as many as possible.
I fully share this view. Every non-functional requirement can make an API more complicated. Below, we’ll look at several non-functional requirements – accessibility, reliability, performance, backward compatibility, portability, and security – and analyze how each of them can complicate an API.
Accessibility
Accessibility means designing products, services, or digital content so that as many people as possible can access and use them. Let’s look at how adding internationalization can make your API more intricate.
Take the bookstore API from before. To handle multiple languages, the language can be selected with a Language header, like this:
English response:
GET /book-store-api/books?price.currency=USD
-h Language:en
{
"books": [
{
"id":"04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets
to writing pristine, maintainable,
and efficient code that stands the
test of time. Discover essential principles,
patterns, and best practices that
empower you to create software
that is not only functional but also
a joy to read and work with. Take
your programming skills to the next
level with this indispensable guide to
achieving clarity, simplicity, and
excellence in your code."
},
{
"id":"9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide to
mastering the art of pragmatic software
development. Learn how to approach
coding challenges with a practical mindset,
leverage powerful tools, and adopt efficient
techniques that lead to success in any
programming project. Unravel the secrets
of effective team collaboration, debugging,
and problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world advice,
this book is your roadmap to becoming
a truly pragmatic programmer."
}
]
}
Internationalization may look like a minor complication, but it does bring challenges. For an integrator, it might seem to be nothing more than one extra header to pick a language. For API developers, however, building the mechanism requires careful thought. A major consequence of internationalization concerns future maintenance: any new language-dependent content returned by the API has to be translated into every supported language. Translation can be automated, but human translators are needed to guarantee quality, which means extra costs for the company developing the API. It can also slow down API development – a simple task that would take a day may stretch to a week while waiting for translations.
That’s why the supported languages should be chosen with care and limited to those that matter most from a product perspective. Adding another language may look easy during development, yet in the long term it can carry high maintenance costs.
Liability
In architecture, liability means that a system or component is responsible or accountable for particular behaviors, functions, or outcomes. It is one of the architecture characteristics meant to establish who owns what and what obligations each part of a system’s design carries. For APIs, liability may relate to meeting requirements stemming from legal obligations, certification, and API specifications.
To show the problem more clearly, let’s return to the bookstore API and consider the following scenario:
The bookstore wants to broaden its payment options by adding new payment methods, such as cryptocurrencies (e.g., Bitcoin, Ethereum) and digital wallets (e.g., Apple Pay, Google Pay).
Here, the new payment methods may force the API to meet regulations and considerations such as:
- Cryptocurrency Regulations: Because cryptocurrencies run on decentralized networks, using them for financial transactions may be subject to specific regulations. The API would have to comply with the applicable cryptocurrency rules, including anti-money laundering (AML) and know-your-customer (KYC) requirements.
- Digital Wallet Regulations: With digital wallets, the API may have to follow rules set by each wallet provider and handle customer data – such as payment credentials and personal information – securely. On top of that, Apple Pay and Google Wallet come with their own refund procedures, which must be handled carefully and correctly.
- Data Protection and Privacy Laws: Once new payment methods are added, the API has to deal with any data protection and privacy issues tied to processing additional financial and personal information.
- Financial Security Standards: The API must follow industry-standard security practices to keep sensitive payment data safe and to prevent fraud or unauthorized access.
- User Consent and Agreements: Depending on the payment method, the API may have to get users’ explicit consent to process payments with particular options and respect any agreements or terms of service tied to those methods.
When adding new payment methods to the bookstore API, the organization has to evaluate and meet these new legal obligations carefully. This may mean updating the API’s functionality, security protocols, and payment processing so they satisfy the regulations that apply to the selected payment methods. Besides the development costs of building these mechanisms, it may also require hiring legal specialists to make sure everything is fully compliant.
Performance
Two key aspects come up when talking about API performance: response time, which measures how long processing a single request takes, and throughput, which measures how many requests the API can handle in a given unit of time. Performance can be improved with various mechanisms, for instance pagination, which retrieves and presents large data sets efficiently, and server-side caching, which keeps frequently requested data at hand and cuts down on repeated processing. Thanks to such optimizations, the API can respond faster, serve more requests, and give users a smoother, more responsive experience.
At the same time, these mechanisms can make the API more complex. Let’s see how adding server-side caching can complicate the Bookstore API. The endpoint shown earlier, which returns available books, is a good candidate for reverse caching – especially when the book list, stock, prices, and exchange rates change rarely:
A correctly implemented server-side cache should be invisible to the client. Done poorly, though, it may cause the client to get outdated responses, or the cache itself may hurt API performance. To prevent this, API providers need to think through the possible challenges and pitfalls carefully, such as:
- Cache Invalidation: Making sure the cache is refreshed or invalidated right away when the underlying data changes, so clients don’t get stale or wrong information.
- Cache Expiration Policies: Setting suitable expiration policies that balance data freshness against cache efficiency, so cached data doesn’t live needlessly long or short.
- Data Consistency: Keeping the cached data consistent with the backend source to avoid inconsistencies and mismatched data.
- Cache Size and Memory Management: Controlling cache size and memory usage to avoid excessive resource consumption and to keep the system scalable.
- Performance Impact: Testing the caching mechanism thoroughly to measure its effect on API performance and avoid creating new performance bottlenecks.
- Security Considerations: Handling the security risks of caching sensitive data by making sure sensitive information isn’t kept in the cache and that access controls are set up properly.
Deciding whether to add a cache mechanism requires careful thought, so it pays to think twice before going ahead.
Backward compatibility
Practically everyone expects APIs to be backward compatible, yet there are several ways to get there, often involving API versioning in one of its many forms. Choices about backward compatibility have a major effect on API complication, which makes it a big topic – one I’ve covered in more depth in a separate article:
- Breaking Changes in APIs: This one looks at options that reduce how often breaking changes happen, or remove them altogether, making transitions easier for API consumers.
Even while pursuing backward compatibility, it’s still essential to make well-informed decisions that suit the particular API use case best.
Portability
API portability is an important characteristic that lets an API be moved to and used on different platforms and systems without major changes. Supporting several data formats is a big part of portability, since it lets the API serve a broader range of clients. Bear in mind, though, that supporting multiple formats can also make your API more complicated.
As an example, let’s take the Bookstore API and assume we want to support both JSON and XML data formats using content negotiation mechanisms.
Books endpoint response in JSON
GET /book-store-api/books?price.currency=USD
-h Accept:application/json
{
"books": [
{
"id":"04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets to writing
pristine, maintainable, and efficient code
that stands the test of time. Discover
essential principles, patterns, and best
practices that empower you to create
software that is not only functional but
also a joy to read and work with. Take
your programming skills to the next
level with this indispensable guide
to achieving clarity, simplicity, and
excellence in your code."
},
{
"id":"9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges with
a practical mindset, leverage powerful
tools and adopt efficient techniques
that lead to success in any programming
project. Unravel the secrets of effective
team collaboration, debugging, and
problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world
advice, this book is your roadmap to
becoming a truly pragmatic programmer."
}
]
}
Books endpoint response in XML:
GET /book-store-api/books?price.currency=USD
-h Accept:application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<root>
<books>
<id>04b1d68-3a85-4ec0-a4e6-8d7a936d4c02</id>
<title>Clean Code: A Handbook of Agile Software Craftsmanship</title>
<author>Robert C. Martin</author>
<stock>3</stock>
<price>
<amount>15</amount>
<currency>USD</currency>
</price>
<description>Unlock the secrets to
writing pristine, maintainable, and
efficient code that stands the test of
time. Discover essential principles,
patterns, and best practices that
empower you to create software that
is not only functional but also a joy
to read and work with. Take your
programming skills to the next level
with this indispensable guide to achieving
clarity, simplicity, and excellence
in your code.
</description>
</books>
<books>
<id>9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773</id>
<title>The Pragmatic Programmer: Your journey to mastery</title>
<author>David Thomas, Andrew Hunt</author>
<stock>5</stock>
<price>
<amount>17</amount>
<currency>USD</currency>
</price>
<description>Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges
with a practical mindset, leverage
powerful tools, and adopt efficient
techniques that lead to success
in any programming project.
Unravel the secrets of effective
team collaboration, debugging,
and problem-solving to become
a highly skilled and adaptable
developer. Packed with timeless
wisdom and real-world advice,
this book is your roadmap to
becoming a truly pragmatic programmer.
</description>
</books>
</root>
Supporting several formats can bring a number of challenges:
- API integrators must specify the content type they want to get data in; if they don’t, they’ll get the default format, provided one is configured.
- Clients need good documentation explaining how to use and handle the different formats properly.
- Every change to the API has to be applied to all supported formats to keep them consistent and avoid discrepancies.
As before, it’s worth asking whether meeting the portability requirement delivers enough business value to make up for the possible increase in complication.
Security
Security is a must-have for web APIs. It sets the rules under which clients may access the various parts of an API, including conditions such as the level of access granted and how often a given client may send requests. This key aspect protects API resources and controls how they are used, making the interaction between clients and the API’s functionalities safe and regulated.
One of the most common ways to authorize clients is to use JWT (JSON Web Token) together with mechanisms such as OAuth 2.0. JWT provides a compact, self-contained way of passing authorization information between parties, which makes it a popular option for securing API interactions. OAuth 2.0, meanwhile, offers a standardized authorization framework that lets access rights be delegated to clients securely without exposing sensitive credentials. Combined, these technologies give a solid basis for protecting API resources while making it easier to grant controlled access to authorized clients.
Still, implementing JWT and OAuth 2.0 comes with a set of challenges and considerations that must be handled with care to keep security intact and effective, for example:
- Token Validity and Expiry: Handling token lifetimes and renewals properly.
- Token Revocation: Quickly invalidating tokens that were compromised or lost.
- Token Scope: Specifying and managing access rights precisely.
- Token Storage and Transmission: Keeping and sending tokens securely.
- Authorization Code Flow: Implementing and running this multi-step flow correctly.
- Token Leakage and Impersonation: Stopping unauthorized access and data leaks.
- Token Management and Auditing: Tracking how tokens are used and what happens with them.
Authorization is almost always unavoidable, but there are situations where it can be skipped. For example, when building an internal MVP where security matters less, dropping elaborate authorization can speed up delivering the MVP without undermining what it’s for.
Poor API structure
Even with lean functional and non-functional requirements, an API can still end up overcomplicated if its structure is inefficient. This part covers the principles and trade-offs that help shape the best API structure for a given use case.
API cohesion
Because the API is the entry point to a component, the component cohesion principles described in Robert Martin’s book “Clean Architecture” apply just as well to API design. Translated to the API context, these rules look as follows:
- REP (Release Equivalence Principle): Put into the API the elements that are released together as one unit, and avoid having multiple APIs share the same version number
- CCP (Common Closure Principle): Group in the API the elements that change for the same reasons and at the same time.
- CRP (Common Reuse Principle): Include in the API only those functionalities that API integrators commonly reuse.
As the book points out, these principles “tend to fight each other”, so they have to be carefully balanced. Mapping the book’s diagram onto APIs reveals the following trade-offs:
Neglecting REP (painful integration): Integrators may have a bad experience because they have to integrate with many APIs. They then need to make sure those APIs are compatible with each other, which makes their work more complex and costly.
Neglecting CCP (painful development): Development may become cumbersome. Ignoring this principle usually points to tight coupling between several APIs, which can seriously slow the API down. Because of that coupling, work on these APIs has to be carefully coordinated, which brings complications and challenges.
Neglecting CRP (painful releases): Ignoring this principle often leaves us with an unwieldy API built by several teams. This usually means long release cycles and broad scopes of change, which increases the risk of introducing failures.
Endpoint granularity
Another important question to ask is:
How many endpoints are there, and how much does each of them cover?
The simple answer: an endpoint should include all the data required to meet the client’s needs – and nothing beyond that.
But can we always achieve that?
When there are several clients with different needs, striking this balance can get hard. What really matters is knowing what happens when endpoints are too broad or too narrow.
Let’s go back to the Bookstore API, for example, and its functionality that returns information about authors and their available books. One way to implement it is to build an endpoint returning all the data about books, authors, and their works:
{
"authors": [
{
"id": "704b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"name": "Robert C. Martin",
"availableBooks": [
{
"id": "c1bdc5c6-7a49-4c45-8e3c-2f47e65a0375",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets
to writing pristine, maintainable, and
efficient code that stands the test of time.
Discover essential principles, patterns,
and best practices that empower you
to create software that is not only functional
but also a joy to read and work with.
Take your programming skills to the
next level with this indispensable
guide to achieving clarity, simplicity,
and excellence in your code."
},
{
"id": "e8c8a24b-5792-4d16-87d5-9e3c8e0b43e8",
"title": "Clean Architecture: A Craftsman Guide to Software Structure and Design",
"stock": 2,
"price": {
"amount": 20,
"currency": "USD"
},
"description": "Design Software Systems
for Maximum Maintainability and Flexibility.
Explore the principles and patterns
behind building clean, robust, and adaptable
software architectures, guided by industry
expert Robert C. Martin. Uncover the secrets
to crafting systems that stand the test of time,
fostering a deep understanding of architecture
design that empowers developers to create
software that is as elegant as it is efficient."
}
]
},
{
"id": "9b5f0b3e-820d-45c7-9847-eb3e3b33ab8f",
"name": "David Thomas",
"availableBooks": [
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges with
a practical mindset, leverage powerful
tools, and adopt efficient techniques
that lead to success in any programming
project. Unravel the secrets of
effective team collaboration, debugging,
and problem-solving to become
a highly skilled and adaptable developer.
Packed with timeless wisdom and real-world
advice, this book is your roadmap to
becoming a truly pragmatic programmer."
}
]
},
{
"id": "ccd61b63-9449-4186-b6f3-ae0fbc3d038a",
"name": "Andrew Hunt",
"availableBooks": [
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how to
approach coding challenges with a
practical mindset, leverage powerful tools,
and adopt efficient techniques that
lead to success in any programming project.
Unravel the secrets of effective team
collaboration, debugging, and problem-solving
to become a highly skilled and adaptable
developer. Packed with timeless wisdom
and real-world advice, this book is your
roadmap to becoming a truly pragmatic
programmer."
}
]
}
]
}
Another option is to use a HATEOAS approach::
{
"authors": [
{
"id": "704b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"name": "Robert C. Martin",
"availableBooks": [
"/book-store-api/books/c1bdc5c6-7a49-4c45-8e3c-2f47e65a0375",
"/book-store-api/books/e8c8a24b-5792-4d16-87d5-9e3c8e0b43e8"
]
},
{
"id": "9b5f0b3e-820d-45c7-9847-eb3e3b33ab8f",
"name": "David Thomas",
"availableBooks": [
"/book-store-api/books/9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773"
]
},
{
"id": "ccd61b63-9449-4186-b6f3-ae0fbc3d038a",
"name": "Andrew Hunt",
"availableBooks": [
"/book-store-api/books/9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773"
]
}
]
}
Which approach is better depends on the context. The first gives a complete structure, so one API call may be enough to fetch everything needed. The trade-off is a larger response payload and more complex documentation. The second keeps the structure simpler, but even basic tasks, such as listing authors along with the titles of their books, may take several API calls. The choice depends on things like how complex the data is, network aspects, and the user experience you want to deliver.
This example shows there’s no single right answer about how big a given endpoint should be. When designing endpoints, though, it’s wise to keep this trade-off in mind:
- If your endpoints are too small, API clients will need many API calls to get what they need, which makes integration more complex.
- If your endpoint grows too large, a big payload may lead to long response times, and such a complex endpoint may be hard to document and use.
Summary
This article covered what API complication is and why it deserves attention. We looked at the problems complicated APIs can cause and at the factors that influence API complexity, such as functional and non-functional requirements and inefficient API design. As we’ve seen, complexity can’t always be avoided entirely, but in many cases there are ways to reduce it.
TL;DR
- How simple your API is can affect how widely it gets adopted.
- The sources of API complexity usually fall into groups such as functional requirements, non-functional requirements, and poor API structure.
- Choose your API’s functionalities with care.
- Limit non-functional requirements to the ones you really need.
- Look after your API’s structure, minding API cohesion and endpoint granularity.