Address details Parameter about api

[missinglink]

👍 very nice, probably best to leave id and layer in the payload but the rest can go

[hkrishna]

should it be false by default?

I think it should be false by default for all endpoints except reverse

[missinglink]

good question about having it default to false

I'm guessing that mapping those fields has a negligible performance impact in the controllers (ie. not enough to measure).

I would enable the fields by default to provide backwards compatibility (although that's not a big deal) and also because it's nice to have uniformity between all endpoints. (ie. turning it off for all but reverse requires a knowledge of the API otherwise consumers may feel it is unexpected behaviour.)

Also, be aware that changing a public API like this might require a prior warning and deprecation notice to the open app team.

[missinglink]

Re: the variable name addressDetails may cause confusion with the future introduction of the .address object.

Wouldn't something like administrativeDetails be more descriptive?

[hkrishna]

Okay to summarize..

1. _Naming:_ addressDetails, details, administrativeDetails, adminDetails ???
2. _Default:_ Should it be false for all endpoints?
3. _Deprecation_ warning/ notice - will the release notes suffice?

As for the naming - instead of being really specific administrativeDetails I think being generic with details would be better because this means that we return the bare minimum information and not a detailed document. In the future, these details can entail other properties related to address, categories, administrative details etc. Does that make sense?

I'm okay with false being a default for all endpoints for the sake of consistency through out the API - but this might prove to be a breaking change for those who use reverse not for the text property but for the admin properties. 😦

As for a way to warn consumers about breaking changes - our API's deprecation policy needs to discussed further - This will make more sense when we have a service that requires a key and access token - because during the key signup we can communicate with the consumers about our deprecation policy. A simple deprecation policy would state that we would announce a breaking (non backwards compatible) change through email and/or Release Notes. Is this a future problem?

[missinglink]

• 👍 for details
• I was thinking true for all endpoints (ie. shows the extended fields by default)
• Deprecation is wholly dependant on the above

[hkrishna]

Okay sounds good. I'll switch to true being default and that way its not a breaking change.

[sevko]

Not to beat a dead horse, but just my two cents on the default value: I think it works either way, since breaking changes aren't presently a huge concern (the service is still v0.x and we explicitly warn users about them, after all), but my intuition is that not returning those values by default will give users the impression that we don't have the data at all, at least until they go ahead and actually read the API docs.

Setting details=false seems like a nice-to-have optimization for, say, mobile consumers, but getting all details back might be more commonly desired by a larger number of users. Thus, I think true is the way to go.

As far as breaking changes are concerned... sending emails to everyone who has an API key will probably be the most effective way to announce them (let's be real, I doubt that the lay consumer will read our release notes). That being said, once we're > 1.0.0, I think it'd be best to avoid them entirely until we make a switch to the next major version.

[dianashk]

Please add acceptance test(s)