Change returned data for localized fields in API version >= 5 (original) (raw)

As of API v5 (which is experimental at the time of writing), localized fields return different data than previous API versions. This change is described in https://addons-server.readthedocs.io/en/latest/topics/api/overview.html#api-overview-translations.

That being said, the new design isn't particularly easy to use from a client perspective. The problem is that when the requested locale isn't available, we return a different locale. Given that v5 returns data keyed by the locale itself, a client won't be able to retrieve the requested locale in this object:

// ?lang=fr and `fr` is available
{ "field": { "fr": "value" } }

// ?lang=fr and `fr` isn't available
{ "field": { "en-US": "value" } }

We'd need to return "something" when the requested locale isn't available so that clients can handle that case. Here is what the API v5+ should return instead:

// ?lang=fr and `fr` isn't available, but we still have it in the returned object!
{ "field": { "en-US": "value", "fr": null, "fallback": "en-US" } }

By returning more information, clients can detect that the request locale isn't available and can use the fallback property to know which locale they can use instead.

For QA: this comment describes the final design: #8105