I used to rave about how RESTful APIs with JSON were so much better than SOAP and other RPC style interfaces, because the responses were so simple and easy to parse.
This holds true for small projects, but as soon as you are working within a large, complex system that involves multiple teams, the benefits of using standards pays off.
I struggled in the past working on projects with companies that had built dozens of loosely-defined APIs, built with the good design intentions in mind, but suffered later from incomplete or inconsistent implementations. The app codebase became much fatter, in an attempt to abstract away those differences into a consistent mental model.
When complexity and communication reaches a certain threshold, it makes sense to invest in standardizing the APIs and responses. I've seen the payoff and am convinced: client libraries and frontend implementations get much simpler, documentation becomes easier, and discussions about how to make changes or design new APIs all but go away.
On the other hand, for small teams and simple services, using a standard like this is probably overkill, unless everyone involved is used to doing APIs this way.
> but as soon as you are working within a large, complex system that involves multiple teams, the benefits of using standards pays off.
That depends a lot on the nature of the project and the standards involved. In my experience, introducing complexity early on in the hope that it will pay off when the project itself becomes complex, leads to exactly what you would intuitively expect: a huge combinatorial code nightmare where productive work asymptotically approaches zero as time progresses.
There is a failure mode in the development of enterprise projects where actual work is being done only at the fringes where the tight external standards have loopholes allowing for the introduction of actual functionality through the backdoor. The resulting systems are of course extremely brittle.
> for small teams and simple services, using a standard like this is probably overkill
There are also simple standards deserving of the name. Small teams and simple services use them quite adamantly.
The "problem" I see with JSON API is not one of complexity (it really isn't, very), it's specificity. It's designed to cover a good range of common web-centric data interchange problems, but like any higher-order standard it carries the weight of certain abstractions and concepts. The pain comes, in my opinion, not from a project/team size mismatch but in cases where these abstractions are ill-suited for the problem at hand.
One of the key factors why plain JSON has become so popular: it's completely malleable. As a result, the actual JSON data on the wire can closely reflect the internal data structures (or at least a logical representation of them) of producers and consumers. The price for this is a relatively tight coupling, but the pain of it is lessened somewhat by the simplicity of the format.
In the end, the old adage of the structure of the project mirroring the structure of the organization probably holds true. When selecting a standard to work with, people choose one that innately reflects how their company works, and they do it for good reason: to reduce friction.
This holds true for small projects, but as soon as you are working within a large, complex system that involves multiple teams, the benefits of using standards pays off.
I struggled in the past working on projects with companies that had built dozens of loosely-defined APIs, built with the good design intentions in mind, but suffered later from incomplete or inconsistent implementations. The app codebase became much fatter, in an attempt to abstract away those differences into a consistent mental model.
When complexity and communication reaches a certain threshold, it makes sense to invest in standardizing the APIs and responses. I've seen the payoff and am convinced: client libraries and frontend implementations get much simpler, documentation becomes easier, and discussions about how to make changes or design new APIs all but go away.
On the other hand, for small teams and simple services, using a standard like this is probably overkill, unless everyone involved is used to doing APIs this way.