3

I Have a REST API endpoint where the caller can supply some optional filters for the results.

GET api/inventory

For example, an object member of a GET request may look like the following

{
   "books" : [
      {
        "id" : 1,
        "description": "this is book 1"
      }       
    ] ,
   "pencils" : [
        {
        "id" : 1,
        "description": "this is pencil 1"
        }
    ]
 }
 ....

Now, this may have optional filters

GET api/inventory?id=true&description=false

As consumers may only want the ids, so we only have a single field, so we don't really need an object for each entity.

In this case, is it "best practice" to

  1. Maintain the same data shape, but just include the single field

ie

{
   "books" : [
      {
        "id" : 1           
      }       
   ] 
   "pencils" : [
        {
        "id" : 1
         }
    ]
}
  1. Since there is just one field, "flatten" the object so we now have something like

    { "books" : [1], "pencils" : [1] }

Option 1. is good as it maintains the same shape regardless, but 2. is more compact when we just have a single property for each object.

I Know either way will work as long as it is documented, but just wondering if there is any accepted "best practice"?

Thanks in advance for any pointers.

  • Your format (2) is totally different. You changed from 2 dictionaries with integer values to an array of strings. – gnasher729 Nov 2 '18 at 2:39
  • 3
    Option #1. Be consistent. The gain of opt #2 over #1 is negligible or none at all. You only will earn the hate of whoever has to develop a Frankenstein client to consume your API. – Laiv Nov 2 '18 at 8:02
  • Didn't mean to change from int to string. Fixed that. Looks like option 1 is how I should be doing it, which is what I thought is the better more consistent way. – peterc Nov 3 '18 at 9:45
5

You make life harder for everyone if you use different formats. Don't use a special case for dictionaries with a single key/value pair.

If you want a compact representation, and don't mind if people hate you, you could store lets say 10 books as

books: {
    ids: [1,2,3,4,5,6,7,8,9,10],
    descriptions: ["first book", "second book", ..., "tenth book"]
}
  • Agreed. Here we could apply the "robustness principle": Be conservative in what you do, be liberal in what you accept from others. In other words, let others request as many fields as they want, but be conservative with the way you respond. – Laiv Nov 2 '18 at 7:50
  • 2
    While I understand where you're coming from with this, damn I'd hate to actually encounter getting output like that :) – mrsmn Nov 2 '18 at 13:33
  • Yep, sounds like everyone agrees NOT to change the shape. I'll be using option 1 – peterc Nov 3 '18 at 9:48

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.