title: Returning Aggregate Data on a Resource
body: <p>Lets say you are leading the development of a new REST API. Greenfield.</p>
  
  <p>And you already have this structure for a person for your REST API, this schema:</p>
  
  <pre><code>{
     "id": 12,
     "name":{
            "first":"Angie",
            "last": "Smith",
            "middle": "joy",
            "maiden": "crowly",
      },
      "address": {
            "street": "1122 Something St.",
            ..and so on...
      },
  ... and so on
  }
  </code></pre>
  
  <p>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".</p>
  
  <p>Would you:</p>
  
  <p><strong>a)</strong> 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.</p>
  
  <p>so for hypothetical url example they'd just call <code>/people?fields=name.last?aggregate</code></p>
  
  <p><strong>b)</strong> 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:</p>
  
  <pre><code>{
       "lastNames": {
              "name": "Anderson",
              "name": "Alvertson",
           ....etc.
        }
  }
  </code></pre>
  
  <p>And who knows what resource this even is, there is no name you can even give this.</p>
  
  <p>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!</p>
  
  <p>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!</p>
  
  <p>And you know that your API may be consumed by many apps, other services or even the public some day.</p>
  
  <p>or </p>
  
  <p><strong>c)</strong> 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.</p>