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

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. https://goo.gl/SmkzNA #DataIntegration #ML