search

facilityregistry / fred-api

Facility Registry API Documentation Website
11 stars 4 forks source link

Documentation clarification re: Filtering #54

Closed ghost closed 11 years ago

ghost commented 11 years ago

In the documentation for queries, the example for filtering on a property (say numbeds) is "?properties.numBeds=2" whereas the fields filter is "?fields=properties:numBeds". Should these be aligned? And if so, which is the correct format that has been implemented?

edjez commented 11 years ago

Good catch.
Will love devs to chime in on the implications for whether we should have properties.numBeds or properties:numBeds in both cases. I like the dot notation, personally.

On Mar 27, 2013, at 10:44 AM, justin-fyfe1 notifications@github.com wrote:

In the documentation for queries, the example for filtering on a property (say numbeds) is "?properties.numBeds=2" whereas the fields filter is "?fields=properties:numBeds". Should these be aligned? And if so, which is the correct format that has been implemented?

— Reply to this email directly or view it on GitHub.

carohadad commented 11 years ago

I think that the purpose of listing the properties after 'properties:' it's to know that everything after this key will be user-defined properties and they should be looked-up in the properties sub object. And to avoid the repetition of "properties."

As a dev, I don't think it would make any difference (performance, ease of implementation/parsing) if instead of listing properties after 'properties' key, they are listed in the same level of the defualt properties: "?fields=name,properties.numBeds,properties.numNurses" vs "?name,fields=properties:numBeds,numNurses".

And I agree with both of you on that it would be clearer if the query and filter format are aligned. I prefer the dot notation too.

mortenoh commented 11 years ago

I think ':' was chosen for field filtering because it was what Google was using. I don't feel too strongly either way, but alignment would be good. I'm leaning towards having ':' since it seems more used in other APIs, but I would be OK with dot notation also.

Of course, properties: { "abc:abc": "abc" } and properties: { "abc.abc": "abc" } is both legal according to the spec, so not sure how we want to handle that. Escaping, or just say that ':' or '.' is simply not allowed in the key part of the properties block.

edjez commented 11 years ago

Re: escaping the Facility object says: The property field code should consist only of letters and numbers and not any special characters, spaces or punctuation

Re dot or colon, Since folks are comfortable leaning to ":" due to presence in other APIs or agnostic we'll go with ":"

Will mark as need to update docs