query-challenge-results.md

Challenge Results

Wesley

Preference: API A

When writing them, I initially thought I would like API B better because most everything was an object with keys to specify the value. But after looking at them more, I like API A. I like that the arrays indicate values that need to be evaluated, while the objects represent pieces that need to be constructed.

no i wouldnt want a pure array implementation, i like that the arrays and objects mean different things which makes it easy to parse quickly. creating B was as easy as A, maybe because i did A first and knew the pattern at that point. B feels like a lot of overhead, having everything be an object. with proper documentation i dont think that type of verboseness is needed.

Julie

Preference: API B

I like B better because it seems more self-documenting. And the positive flipside of verbosity is explicitness.

Michael

Preference: API B

I like style B better. I like the explicitness of objects, even though they are considerably less terse. I also feel like if we decide to add things to certain operators it's easier to do it under a property name than an index into an array. Something that I think could be useful is a way to specify multiple operators for a single column but I'm not sure how this would work (maybe _or and _and blocks could have an optional column field). Additionally I think that condition should be an array that is implicitly the value of an _and block.

Taylor

Preference: API A

This is how I naturally wrote it. It felt less verbose, more succinct and concise. I worry that it may be too concise though since arrays aren't self-documenting like objects.

Tyler

Preference: API B

API A Example

API A tends to be the trickier one to implement since it's not immediately obvious from the examples if it's a hybrid of arrays or it it's just all arrays.

{
  "offset": 0,
  "limit": 5000,
  "condition": {
    "_and": [
      [ "firstName", "_eq", "Taylor" ],
      [ "lastName", "_neq", "McGann" ],
      {
        "_or": [
          [ "age", "_lt", 20 ],
          {
            "_and": [
              [ "age", "_gte", 30 ],
              [ "age", "_lt", 40 ]
            ]
          },
          [ "age", "_gte", 50 ]
        ]
      }
    ]
  },
  "orderBy": [
    [ "firstName", "asc" ],
    [ "age", "desc" ]
  ]
}

Conclusion

Going to write the API spec according to API B (all objects with explicit, self-documenting keys).

Additional Questions

• Q: Should we invite other engineers on our team to take the challenge?
  • A: Yes.
• Q: Should we change the operator constants at all? (i.e. is there any reason to not use the familiar symbols?)
  • A: Make them all options. Document them all. Pick one to show in examples.