I am a sole developer and I recently wrote a new web application in the form of a API with Swagger and front-end. This was customers could use the API on their own, usually forscripting.
It is nearing completion, and my boss who is not a developer brought up that the API looks too difficult for the consumers, and he feels like there will be some push-back. For example, when you hit /api/customers you may get back related data in the form of Ids: { name: "Bob", FavoriteProducts: [ 1, 2, 5] }
.
This works great for the front-end. There are many pages that load the related data on demand, sometimes we show a customer summary for example and don't use the FavoriteProducts, sometimes we show a huge table of customers so all that related data would take forever to load.
He says, the customers will not want to have to make separate calls for the related data, and he says on an insert it would be easier if they could provide product names and have them mapped to their Ids and persisted magically on the back end: { name: "Bob", FavoriteProducts: [ "Plastic Spiders", "Candy", "Pumpkins"] }
. This sounds innocent enough but this is a gross simplifications of a lot more data and a lot more endpoints, lookup tables, code tables, etc.
We haven't had our first consumer yet, so we don't know if this will actually be a problem, but he said from his experience scripting, he wants to make as few API calls as possible.
I don't fully agree, I do think we should strive to make our customers lives easier, especially since it is a competitive world out there. But I also worked hard to make a RESTful API with good performance and well documented via Swagger which is consumable by Swagger client generators (like NSwag) who can read the docs and spit out a client in almost any language. I think there's a line to balance when it comes to adding a bunch of extra back-end code and technical debt because someone does not want to make 2 API calls.
I am guessing GraphQL could have made this easier, but I think this boss would have said it would be too hard for the scripting customers to learn this new language, and he wouldn't want to spend the time for me to learn it because he vetoed Angular for this project for that exact reason. Plus I didn't think this would be an issue. We re-wrote a large legacy app that stored all of its data in a single table to a RESTful API with proper lookup tables and data validation. So I assumed it would complicated consumption a bit and i figured that would be fine.