Estimate project
← All posts

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.

23 min read
ArchitectureSoftware DevelopmentAPIAPI Design

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:

  1. Currency Fluctuations: Because book prices depend on exchange rates, they may be unstable, which could mean customers see inconsistent prices.
  2. Refund Policy Complexity: A refund policy for purchases in different currencies can get complicated, since the amount refunded may change along with exchange rates.
  3. Exchange Rate Mechanism: Something has to fetch and manage exchange rates so that currency conversions are correct.
  4. 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:

  1. 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.
  2. 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.
  3. 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.
  4. Financial Security Standards: The API must follow industry-standard security practices to keep sensitive payment data safe and to prevent fraud or unauthorized access.
  5. 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:

  1. 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.
  2. Cache Expiration Policies: Setting suitable expiration policies that balance data freshness against cache efficiency, so cached data doesn’t live needlessly long or short.
  3. Data Consistency: Keeping the cached data consistent with the backend source to avoid inconsistencies and mismatched data.
  4. Cache Size and Memory Management: Controlling cache size and memory usage to avoid excessive resource consumption and to keep the system scalable.
  5. Performance Impact: Testing the caching mechanism thoroughly to measure its effect on API performance and avoid creating new performance bottlenecks.
  6. 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:

  1. 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.
  2. Clients need good documentation explaining how to use and handle the different formats properly.
  3. 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:

  1. Token Validity and Expiry: Handling token lifetimes and renewals properly.
  2. Token Revocation: Quickly invalidating tokens that were compromised or lost.
  3. Token Scope: Specifying and managing access rights precisely.
  4. Token Storage and Transmission: Keeping and sending tokens securely.
  5. Authorization Code Flow: Implementing and running this multi-step flow correctly.
  6. Token Leakage and Impersonation: Stopping unauthorized access and data leaks.
  7. 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.