Guild Wars 2

The title pretty much says it all. The HTTP 1.1 Protocol (See Section 14.4 for more details) defines an Accept-Language header field which can be used to request content in a specific language.

This is imo the far better choice than url parameters, since it
a) allows more than one value, thus allowing fallback values
b) keeps the url clean(er)

a) Why would you want a fallback value? You know that the API supports 4 (or maybe 6 with zh & ko) languages which you can check easily in your application and then send the correct lang parameter.
b) Who cares on a clean URL which only the backend sees? From a php point of view it’s the easiest thing to throw an array of parameters into http_build_query() - so why would i want to go the extra mile to send another header? I mean, i can even send the access_token parameter and save the Authorization Bearer header.

Please note that RFC 2616 is obsoleted. Use RFC 7230 instead.

I vote for adding support for the ‘Accept-Language’ header, but keeping the ‘lang’ parameter around for legacy reasons.

smiley.1438:

Why would you want a fallback value? You know that the API supports 4 (or maybe 6 with zh & ko) languages which you can check easily in your application and then send the correct lang parameter.

I think you just accidentally proved why fallback values are a good idea. Does this endpoint support 4 or maybe 6 languages? Nobody knows until you query it. That’s why it would be helpful if we could specify all languages that we are willing to accept in a single request.

An example (please beware the &amp ; forum bug):

Right now, this request crashes with an error.
https://api.guildwars2.com/v2/colors?page=0&lang=zh

GET /v2/colors?page=0&lang=zh HTTP/1.1

—
To get the fallback value, you have to do another HTTP GET
https://api.guildwars2.com/v2/colors?page=0&lang=en

GET /v2/colors?page=0&lang=en HTTP/1.1

—
With the header implementation, you can do all this in a single request.

GET /v2/colors?page=0 HTTP/1.1
Accept-Language: zh, en

Since API support for korean and chinese hasn’t been officially announced, we can safely assume there are only 4 languages. Also, it wasn’t a “maybe 6” as in “we don’t know” but as in “once it’s been announced”.

Also, the Accept-Language header can be a pain in the kitteh when working in web applications (i assume you’re about to write a desktop application).
For example: this forum heavily relies on the Accept-Language header and redirects you to “your” language all the time (german in my case) – even when using the language-prefix “forum-en”. So i have to change the default language in my browser to english to prevent redirects. So much for Accept-Language.

I don’t really care for a ‘Accept-Language’ header, the lang parameter can do everything we really need and is way easier to work with (Just think about all the ajax calls that will break because the developer is not sending a the header, but the browser is using the system language, and the application expects the response to be in english).

For now validating the language against [de,en,es,fr] before sending is easy enough, or if you’d want you can check the ‘Content-Language’ header.

I didn’t consider that you can’t change the browser’s Accept-Language header in javascript. That’s kinda lame.

Still, there’s an easy API side solution: use the ‘lang’ parameter if it is set; otherwise, use the ‘Accept-Language’ header.