Many find they have not one, not two, but dozens of APIs within their organization. RESTful APIs are descriptive, not prescriptive. That is, there is so much about the creation of an API interface design that is open to personal interpretation. Left alone, odds are these interfaces will share few similarities. Telling multiple development teams to do some Googling and expecting them to arrive at exactly the same "correct" interface conclusions is ripe for disaster. The flexibility of API interface design, along with the body of seemingly contradictory advice, can be be a hinderance to scaling without central guidance.
In response to this problem, some companies create an API style guides. Just because you create a persuasive, even comprehensive, document for how to do something, however, it doesn't mean people will. That goes double when the creators of an API perceive that the API style was dictated to them, rather than it is something done in their long term best interest.
The consist and cohesive approach to API interface design within an organization is more important than the industry (or pundit) perceived "correctness". The more microservice-like the granularity, the more important this becomes.
Consider another interface that we are all familiar with: the electrical outlet.
An enterprise is like a house. There are numerous individuals installing outlets (sometimes there are even multiple contractors for a single room). Without a geographical context, how do contractors choose the "correct" outlet? Is an European electrical interface more or less "correct" than a North American one?
Of course not - all of the interfaces pictured carry electrical current. All are perfectly fine if consistently and cohesively used throughout. If a single house has an unpredictable assortment of electrical outlets then even doing simple connections incur an additional cost. The lack of consistency and cohesion has created friction to usage.
An enterprise should strive to establish a set of API guidelines, or common practice, that fulfills their business intent. This might be creating the style guide mentioned above. However, that is only the first step. The bulk of subsequent effort is relentlessly ensuring that the consistent and cohesive application of those common practices happens.
Everybody understands consistency. What is less obvious, when enforcing enterprise API guidelines, is the cohesion between interfaces. The Internet, my favorite source for Schrodinger's Cat jokes, defines cohesion as:
"the act of forming a uniform whole"
But what does that mean for API interface design? Consider the following image.
At any table you're likely to find salt and pepper for seasoning food. However, here we see a salt shaker and pepper corns. While the two items are cohesive - they are both used to season food - the interface is inconsistent. Everyone can use a salt shaker. However, having to use the pepper corns in their current state is problematic.
In this image we've solved our interface consistency problem: we've got salt spray for creating luscious, beach-like hair... and we have pepper spray. They're both sprays. The interface is consistent. However, there is no cohesion. There is no uniform whole. You wouldn't use these items together (at least I hope not). And, despite being "salt" and "pepper", neither one has anything to do with a meal condiment. Consistency of the interface doesn't mean much if there is no cohesion in how the services can be combined.
Here we have two versions of an interface design that is both consistent and cohesive. The salt and pepper shakers are fine. Or, if you would so choose, the salt and pepper mills also demonstrate a consistent interface with cohesive behavior. What is paramount is that an organization standardizes on one interface design or the other. They shouldn't try to straddle both. Or, even more common, they shouldn't hope consistency and cohesion just happens over time, since "good" will be self-evident.
That is just a recipe for confusion.
