allProperties & fields parameter on GET

[ghost]

Just a clarification (I may have missed this on a call). Are the allProperties and fields parameters supported on a GET operation or does the facility registry return all properties on a GET facility by default? i.e. does one need to do this:

GET http://facilityregistry.org/api/v1/facilities/0X9OCW3JMV98EYOVN32SGN4II.json?allProperties=true

or is allProperties=true implied because it is a GET on a specific facility?

[edjez]

As far as I understood it the purpose of allProperties=false was to reduce the bulk of data returned for simpler enumeration/matching needs on a query with large result sets.

Therefore, allProperties is not a parameter on an individual get; and the facility object returned on an individual get will have all fields (and will look just as if it had been returned in a set query with allProperties=true). I would not say it is 'implied' as that may be read as 'default' i.e. 'if you add the argument you may get the allProperties=false behavior' which is not supported. I would just say an individual get returns the whole facility object.

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

Just a clarification (I may have missed this on a call). Are the allProperties and fields parameters supported on a GET operation or does the facility registry return all properties on a GET facility by default? i.e. does one need to do this:

GET http://facilityregistry.org/api/v1/facilities/0X9OCW3JMV98EYOVN32SGN4II.json?allProperties=true

or is allProperties=true implied because it is a GET on a specific facility?

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

[mortenoh]

Hm. Why are we using true/false here, and we have limit=off another place.. On 28 Mar 2013 01:20, "edjez" notifications@github.com wrote:

As far as I understood it the purpose of allProperties=false was to reduce the bulk of data returned for simpler enumeration/matching needs on a query with large result sets.

Therefore, allProperties is not a parameter on an individual get; and the facility object returned on an individual get will have all fields (and will look just as if it had been returned in a set query with allProperties=true). I would not say it is 'implied' as that may be read as 'default' i.e. 'if you add the argument you may get the allProperties=false behavior' which is not supported. I would just say an individual get returns the whole facility object.

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

Just a clarification (I may have missed this on a call). Are the allProperties and fields parameters supported on a GET operation or does the facility registry return all properties on a GET facility by default? i.e. does one need to do this:

GET http://facilityregistry.org/api/v1/facilities/0X9OCW3JMV98EYOVN32SGN4II.json?allProperties=true

or is allProperties=true implied because it is a GET on a specific facility?

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

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/55#issuecomment-15542690 .

[mortenoh]

I feel the default here should be /api/facilities?allProperties=false for GET all. And /api/facilities/UUID?properties=true for single facility. But it might be a bit late in the game to change.

Giving out ALL data on a simple request seems less useful for me. Unless you are doing a server-to-server sync, which is our (dhis2) most common usecase, but I have a feeling that the API is support to be more tailored towards normal clients, which means less data upfront is good. Probably just name and href is needed.

(This is what we do with our own DHIS2 web-api)

[edjez]

Since paging is active by default this is not going to be a meaningful protection to return just core props as we would only return the first N facilities anyways.... And as soon as developers opt in to putting flags to control what they get they are making explicit choices about it and reading docs etc.

The default is we return a few complete facilities: they can decide to get a lot of slim facilities, a lot of complete facilities, or a few slim facilities. In your big-batch-sync DHIS use case, you can choose to get a lot of complete facilities by turning pagination off.

Note : The "all properties" argument specifies whether all properties or just the core properties are returned. Core properties include name, lat/long, user IDs, uuids, href, active flag, and timestamps. (see here for the complete list: http://facilityregistry.org/#facility-resource)

I suggest to close leaving the defaults as they are: a GET on a specific facility returns all properties. Will update docs to clarify