I came across this blog from Tyk - Your data model is not an API, while I was lying on my bed ready to sleep.
To me, this is taking a dig at CA Live API Creator. :)
Very insightful article, indeed. This is coming from API consumers' (Customers) perspective, rather than from API developers.
Sometimes, we keep forgetting who our pay-masters are. This is why I keep reminding my team - they have to make our customers happy, not me.
I totally agree with the conclusion:
- Your API consumers want an API that is familiar to them, not to your implementation team
- Your API consumers want an API that is fast to integrate for them, not for your internal team to implement
- Your API consumers want an API that is flexible by offering capabilities to get things done, without creating lots of HTTP calls and stitching data together to achieve their desired outcomes
Finally, it is important to remember that 5 hours saved by your team may cost 10s to 100s of hours by your API consumers. ... A great API design makes it easy for API consumers by hiding internal implementation details, leading to faster integration and happy developers.
It is definitely not easy to design an API.
From our experience with a large insurer in Singapore, we know it could take weeks to design a useful API. Sometimes, we could end up having heated arguments with our customer's application teams, because we do not agree with certain design methodology. But the end result is great! There's nothing wrong with disagreements, as long as it's for the good of the project.