rest - Returning Aggregate Data on a Resource -

lets leading development of new rest api. greenfield.

and have structure person rest api, schema:

{    "id": 12,    "name":{           "first":"angie",           "last": "smith",           "middle": "joy",           "maiden": "crowly",     },     "address": {           "street": "1122 st.",           ..and on...     }, ... , on } 

and lets have client of api (in case whole new web team that's been hired remote , inexperienced) come , "hey need list of unique last names in system".

would you:

a) tell person "ok, sure, names part of our people resource endpoint. can return list of people give name.last field back, , you'd 1 person every different name.last exists". give them aggregated grouping of people in order satisfy need every unique last name in database people.

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

b) oh ok, we'll create special endpoint you, don't know resource or endpoint url yet, we'll give this:

{      "lastnames": {             "name": "anderson",             "name": "alvertson",          ....etc.       } } 

and knows resource is, there no name can give this.

and forgot benefits of rest because client refused understand have architecture , convention maintain , offer them need through resources setup think it's odd have adhere sort of resource template whatsoever , expect build infinitely/endless custom resources there no consistency or no way name these resources because they're coupling api application , expect adhere whatever contract feel should design...meaning feel can literally tell how design api , have no say!

and know if give in 1 time , bypass current rest resource here "person" they'll expect forgo design decisions you've made or want make api since gave them saying don't care design yet you're platform team creating api consumption company-wide!

and know api may consumed many apps, other services or public day.

or

c) f , quit alltogether due stress of continually trying explain them rest , why you're trying keep conventions simple idea of resources make sense , trying reuse resources @ related data, , find better place , team work with, because after constructively , tactfully trying tell them time , time again have conventions we're sticking on api, web team still feels need dictate rest api design 100% don't have clue rest , don't care say...they think can own api though it's , platform team building out company not consumption possibly other apps, services, or exposing api public consumers in future.

from experience common problem in cooperation between rest (or other) api provider , web, mobile, whatever api consumer.

i try stick rules as possible , force consumer accept conventions , architecture. why? because of reasons mentioned, 1 of them crucial: api may become public day , can't let introduce new endpoint every time consumer needs display users pink skirts.

thus a makes sense me , presents restful approach.

b doesn't make sense reasons mentioned above. remember in kind of problems difficult introduce first dedicated endpoint. when it's done, next 1 matter of time.

sometimes c makes great sense me still try explain ;)

remember when designing/implementing api must consistent rules - if set rules yourself.