Returning Aggregate Data on a Resource

Question

Lets say you are leading the development of a new REST API. Greenfield.

And you already have this structure for a person for your REST API, this schema:

{
   "id": 12,
   "name":{
          "first":"Angie",
          "last": "Smith",
          "middle": "joy",
          "maiden": "crowly",
    },
    "address": {
          "street": "1122 Something St.",
          ..and so on...
    },
... and so on
}

and lets say you have a client of your API (in this case a whole new web team that's been hired that are remote and very inexperienced) come to you and say "Hey I need a list of all unique last names in the system".

Would you:

a) Tell that person "OK, sure, well names are already part of our people resource endpoint. We can return just a list of people that will give you just the name.last field back, and you'd only get one person for every different name.last that exists". Basically just give them an aggregated grouping of people in order to satisfy their need for basically every unique last name in the database for people.

so for hypothetical url example they'd just call /people?fields=name.last?aggregate

b) Oh ok, we'll just create a special endpoint for you, we don't know what that resource or endpoint url would look like yet, but we'll give you just this:

{
     "lastNames": {
            "name": "Anderson",
            "name": "Alvertson",
         ....etc.
      }
}

And who knows what resource this even is, there is no name you can even give this.

and you forgot all the benefits of REST because your client refused to understand that you have an Architecture and convention to maintain and you offer them what they need through resources you setup but they think it's odd that they have to adhere to any sort of resource template whatsoever and expect you to build infinitely/endless custom resources which there is no consistency or no way to even name these resources because they're coupling your API to their application and they expect you to adhere to whatever contract they feel you should design...meaning they feel they can literally tell you how to design your API and that you have no say!

And you know if you give in just this one time and bypass your current REST resource here which is "Person" that they'll most likely expect you to forgo any design decisions you've made or want to make with your API since you gave into them saying they don't care about your design yet you're the platform team creating this API for consumption company-wide!

And you know that your API may be consumed by many apps, other services or even the public some day.

or

c) just say f this and quit alltogether due to stress of continually trying to explain to them REST and why you're trying to keep certain conventions even the simple idea of resources that make sense and trying to reuse those resources to get at related data, and find a better place and team to work with, because after constructively and tactfully trying to tell them time and time again that we have conventions we're sticking with on the API, the web team still feels they need to dictate your REST API design 100% which they don't have a clue about REST and so they don't care what you say...they think they can just own the API even though it's you and the platform team building it out for the company for not only their consumption but possibly for other apps, services, or even exposing this API to public consumers in the future.

Answer 1

From my experience this is the most common problem in cooperation between REST (or any other) API provider and web, mobile, whatever API consumer.

I always try to stick to the rules as much as possible and force consumer to accept my conventions and architecture. Why? Because of reasons you mentioned, which one of them is crucial: your API may become public some day and you can't let yourself to introduce a new endpoint every time the consumer needs to display users with pink skirts.

Thus a makes sense to me and presents the most RESTful approach.

b doesn't make sense for the reasons mentioned above. Remember that in this kind of problems the most difficult is to introduce the first dedicated endpoint. When it's done, the next one is just a matter of time.

Sometimes c makes great sense to me but I still try to explain ;)

Remember that when designing/implementing the API you must be consistent with the rules - even if you set the rules by yourself.