mjhjmtu

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.

If you've ever used RESTful APIs, you've come across at least one where you have to make multiple API calls to get all the data you want. It just kinda comes with the territory. The benefits of a granular API are that you can get exactly what you need and nothing you don't. The cost is multiple calls, which can get bad if you need to build a deep object graph.

The flip side is to RETURN EVERYTHING. Favorite products, colors, upcoming sales, shipping details to Madagascar, etc. It's plenty friendly to read, but can be a pain to sift through when you only want the customer name and address. It also can have performance problems, especially with returning so much data.

So what do you do?

My first recommendation would be to stick with a pretty simple API like you have. Most developers won't be caught off guard by this. On top of that, if you don't have any customers to tell you what they want, how can you know what they want? You can guess, but as anyone who's developed software for a while can tell you, guessing what a customer wants only works out some of the time. Most of the time you get it wrong (or at least, not entirely right).

If your boss is insistent, you could provide a kind of compromise by allowing API users to request what data they get back. Say you have the following endpoint and response:

/customers/1 -> name: "bob", favoriteProducts: [ 1, 3 ] 

Now say you add a parameter to say you want the full product information back:

/customers/1?favoriteProducts=full -> name: "bob", favoriteProducts: [ id: 1, name: "plastic spiders", ... , id: 3, name: "pumpkins", ... ] 

You can add as many configuration options as make sense. Just make sure to fully document them so there aren't any surprises.

You are not tailoring your API to customers. Your boss wants you to tailor the API to his wild guess what customers might want.

As a customer of APIs (software developer, so I’m your customer, not the people your boss wants to sell to): The worst ever is an API that tries to be clever. Don’t write an API that tries to be clever. Unique IDs are an excellent way to access an API.

If customers are told by their developers that they don’t like the API then you can implement things - after your boss makes sure the customer pays. Remember the iron rule of a successful business: The customer is always right - if the customer pays.

I don't think that there is much to gain by opposing the boss here. He is the one who does the business decisions and whose job it is to anticipate the needs of his customers.

If following the patterns your boss suggests would make your standard front-end harder to create, maintain and/or hurt its performance, then you might want to consider to create two versions of every API endpoint. One "machine-friendly" version tailored for the requirements of the frontend and one "user-friendly" version tailored for the needs of scripters at the customer.

Creating this separate API in addition to your current one would likely not be any more work for now because you don't need to change anything on the already working client-side. But keep in mind that it will increase maintenance and documentation overhead in the long term. You might be able to reduce that overhead by sharing as much code as possible between them. You could implement one endpoint by calling the other.

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.

Your boss has a use case here and your concern about performance is also valid. I don't think they are conflicting and addressing them both will make a better API.

For the API, I have to say that if I do a GET /api/customers/ I prefer to see a response like name: "Bob", FavoriteProducts: [ "Plastic Spiders", "Candy", "Pumpkins"]

On the performance side, I know you did some benchmark from comments, I think you need to profile your differently. The reason for that is the performance issues are there to be fixed, they shouldn't shape the form of the API (within reasons, of course).

One way to see this is to put sample responses in files and have a server serve these static files so you can see the difference between the two API style. I.e. :

GET /api/customers <-- returns fav product IDs
GET /api/favorite_products/1
GET /api/favorite_products/2
GET /api/favorite_products/5

vs.

GET /api/customers <-- this one returns related fav products

I didn't try that myself but pretty sure the second one will be faster because of less round trips. This is what most customers would want. Even if I don't need the fav products, doesn't bother me, it's still only one call.

Of course, when implemented with all the extra look ups there will be performance hit and have to be addressed. It is not impossible to remove most of the extra load, e.g. by storing data differently, using in-memory key-value store, caching etc.