Suppose you are leading the development of a new REST API. Greenfield
And you already have this structure for humans for your REST API, this diagram:
{ "id": 12, "name":{ "first":"Angie", "last": "Smith", "middle": "joy", "maiden": "crowly", }, "address": { "street": "1122 Something St.", ..and so on... }, ... and so on }
and say that you have a client for your API (in this case, a whole new web team came to you that was hired, which was remote and very inexperienced) and said: "Hey, I need a list of all the unique names in the system."
You:
a) Tell this person: “OK, of course, the column names are already part of the endpoint of our people’s resource. We can only return a list of people who will give you only a name. and you will get only one person for every other .last name, which exists". Basically, just giving them an aggregate group of people to satisfy their need for basically every unique last name in the people database.
so for a hypothetical url example they just call /people?fields=name.last?aggregate
b) Oh well, we’ll just create a special endpoint for you, we don’t know what this resource URL or endpoint will look like, but we will give you exactly that
{ "lastNames": { "name": "Anderson", "name": "Alvertson", ....etc. } }
And who knows what resource it even is, there is no name that you can even give.
and you forgot all the advantages of REST because your client refused to understand that you have an architecture and agreement for support, and you offer them what they need using the resources you configure, but they find it strange that they should stick to any type of resource template and expect that you will create infinitely / endless user resources that don't have consistency or don't even let you name these resources because they associate your API with their application and they expect you to stick to any of a contract that they think you should design ... which means that they can literally tell you how to develop your API and what you cannot say!
And you know, if you give only once and go around your current REST resource here, which is the “Face”, that they most likely expect that you will discard any design decisions that you made or want to make using your The API since you let them say that they don’t care about your design, but you are the platform that creates this API for company-wide consumption!
And you know that your API can be consumed by many applications, other services, or even the public on some day.
or
c) just say it and stop all because of stress, constantly trying to explain REST to them and why you are trying to keep certain conventions even in the simple idea of resources that make sense and trying to reuse these resources to get related data and find a better place and team to work, because after constructively and tactfully trying to tell them again and again that we have agreements that we adhere to in the API, on the Internet the team still believes that they need to dictate your REST API design to 100 % and they don’t have a hint about REST, and therefore they don’t care what you say ... they think they can just own the API, even if it’s you and the platform team creating it for the company, not only for their consumption, but maybe for other applications, services, or even providing this API to public users in the future.