Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

API Design, Either the Provider Does the Work or the Consumer Will Have to

DZone's Guide to

API Design, Either the Provider Does the Work or the Consumer Will Have to

In the world of API design, who should do more of the heavy lifting? The provider? The consumer? We explore one opinion. Do you agree?

· Integration Zone ·
Free Resource

SnapLogic is the leading self-service enterprise-grade integration platform. Download the 2018 GartnerMagic Quadrant for Enterprise iPaaS or play around on the platform, risk free, for 30 days.

I'm always fascinated by the API design debate and how many entrenched positions there are when it comes to the right way of doing it. Personally, I don't see any right way of doing it, I just see many different ways to put the responsibility on the provider or the consumer's shoulders or sharing the load between them. I spend a lot of time profiling APIs and crafting OpenAPI definitions that try to capture 100% of the surface area of an API, something that is pretty difficult to do when you aren't the provider, and you are just working from existing static documentation. It is just hard to find every parameter and potential value, exhaustively detailing what is possible when you use an API.

When designing APIs, I tend to lean towards exposing the surface area of an API in the path. This is my personal preference for when I'm using an API, but I also do this to try and make APIs more accessible to non-developers. However, I regularly get folks who freak out at how many API paths I have, preferring to have the complexity at the parameter level. This conversation continues with the GraphQL and other "query language folks" who prefer to craft more complex queries that can be passed in the body to define exactly what is desired. I do not feel there is a right way of doing this, but it does reflect what I said early about balancing the load between provider and consumer.

The burden of defining and designing the surface area of an API resides in the provider's court—only the provider truly knows the entire surface area. Then I'd add that when you offload the responsibility to the consumer using GraphQL, you are limiting who will be able to craft a query, putting API access beyond the reach of business users and many developers. I feel that exposing the surface area of an API in the URL makes sense to a lot of people and puts it all out in the open. Unless you are going to provide every possible enum value for all parameters, this is the only way to make 100% of the surface area of an API visible and known. However, depending on the complexity of an API, this is something that can get pretty unwieldy pretty quickly, making parameters the next stop for defining and designing the surface area of your API.

I know my view of API design doesn't sync with many API believers across many different disciplines. I'm not concerned with that. I'm happy to hear all the pros and cons of any approach. My objective is to lower the bar for entry into the API game, not raise or hide the bar. I'm all for pushing API providers to be more responsible for defining the surface area of their API, and not just offloading it on consumers to do all the work unless they implicitly ask for it. In the end, I'm just a fan of simple, elegantly designed APIs that are intuitive and well documented using OpenAPI. I want all APIs to be accessible to everyone, even non-developers. I want them accessible to developers, minimizing the load on them to understand what is happening, and what all the possibilities are. I just don't want to spend too much time onboarding with an API. I want to go from discovery to exploration in as little time as possible.

With SnapLogic’s integration platform you can save millions of dollars, increase integrator productivity by 5X, and reduce integration time to value by 90%. Sign up for our risk-free 30-day trial!

Topics:
integration ,api design ,consumer ,provider ,opinion ,apis

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}