switch from languages= to language in url

[wardi]

Here is my suggestion for APIs with separate language versions based on URL.

• removed the languages= section because its primary use would be the same: select only a single language to be returned.
• maintained the same format with languages nested in objects to clearly mark language content and to make implementing and combining both methods easier
• require a known URL pattern to move between languages instead of adding fields to metadata

[LaurentGoderre]

I personally don't agree with this. It limits to only choosing one language, as opposed to being able to send a comma separated list of language in addition to make URLs more complicated.

[LaurentGoderre]

For example http://api.example.gc.ca/resource/[id]?lang=en or http://api.example.gc.ca/resource/[id]?lang=es,it

[wardi]

@LaurentGoderre yes. I agree that it is worse than what was there before

I'm submitting this in case the decision to go with separate language endpoints comes down regardless. Requesting and merging http://api.example.gc.ca/en/resource/[id] and http://api.example.gc.ca/it/resouce/[id] is at least possible with this scheme.

[LaurentGoderre]

Gotcha! Fingers crossed

[chrismajewski]

Yea, tough call. You know at least a few environments with split languages would baulk at a single path.

Sometimes it feels like we are trying to define a single shape for water.

Lets go with that, no matter what you chose someone will want it differently but at the very least this is supported by logical structure and reasoning in use.

This will, like every thing else, be reviewed. We'd like a first presentable draft by mid early in January, we'll iterate from there.

[LaurentGoderre]

Can we offer both option with the other one being preferred? It would be good if all new API followed the other convention.