Where Do You Like Your API Complexity?
I prefer my API complexity at the path, query, then schema levels of my API design—specifically in that order. I don’t mind a huge number of individual API calls to get the job done because I just script away this aspect of API complexity. However, I do fully understand that many folks prefer their complexity at the query and schema levels over having lots of individual paths. I find that developers love to rant about imperative API complexity, and in my experience the folks who don’t like path level API complexity are also some of the most vocal types of folks who are very confident that their way is the right way, when in reality, there is no right way—just the way YOUR consumers will want or need to access the API resources you are serving up.
In my experience, how someone learned about the web, and then APIs, dictate much of where they like their API complexity. If developers prefer their complexity at the query parameter layer their API doorway was the web. If developers prefer their complexity in the schema, their doorway was likely mobile. If you understand the role that paths can play in managing complexity, you’ve probably have embraced the overall concept of web APIs. If you understand the opportunity and necessity of sensibly spreading complexity across the path, query, and schema layers of your API, you probably don’t just have experience providing APIs, you probably have a lot of experience supporting many different types of API consumers—the key that unlocks the door to seeing the bigger picture of managing API complexity.
Not all API consumers are created equal. They have different views of what an API is, and how you use one. If you’ve supported a wide audience of API consumers, you realize there is no single silver bullet when it comes to where you offload your API complexity. You have to make tradeoffs at every turn when designing your API, and it’s underlying schema. New users won’t know your schema intimately, and respond well to simple, well defined API paths with the ability to dabble in complexity with a few query parameters. Your veteran users will know your schema and will see each API call made as cumbersome and demand a single robust way to get what they need. Not all API consumers will see API the same way you do, something that will exponentially increase depending on how public your APIs are.
Personally I like to avoid complexity at all costs. However, I work hard to spread my API complexity equally across API paths, query parameters, as well as the schema. I’d also add that I personally prefer leverage headers for much of the complexity we burden our query parameters and schema with. Things like authentication, pagination, sorting, filtering, etc. However, I also understand that many developers don’t see headers, so I tread thoughtfully here, even though I personally prefer my complexity done using headers in some standardized way. API complexity is a topic I should visit more often here on the blog. I may even add it as a stop along the API lifecycle. Making it a conscious stop helps force me to pause and think about what I am doing, forcing me to think about complexity. Pushing me out of my API silo and this more about how others might view my API, moving beyond just my default API belief system.