Supporting multiple languages in a REST API - rest

Question

I have a collection of cities for which I'm creating a REST API (my first REST API). Each city has a number of language independent things, such as founding date and population count. Cities also have things that depend on the language, such as the title and a short description. Internally the city documents have this format:
{
"population": 9042,
"name": {
"en": "Berlin",
"nl": "Berlijn",
// ...
},
// ...
}
The users of my API always want to view the city info for a specific language only, and get back something like:
{
"population": 9042,
"name": Berlin,
// ...
}
I've made these accessible via /cities/:id/:language_code, for instance cities/123/en. Now I want to implement listing of cities: GET /cities. There the requested language is also needed. Since this would result in /cities/:language_code, I'm getting the impression putting this at the end of the url is not a good idea, and suspect I'll be better off with /en/cities/...whatever....
How is this typically done in REST APIs? Any big, nicely implemented, API out there that is a good example?

Answer 1

REST API's are based upon HTTP protocol, so they can use the headers, that are traditionaly used to defined the prefered locale.
So I would use a Accept-Language parameter for this.
# Request
GET /cities/.... HTTP/1.1
Host: www.example.org
Accept-Language: en,en-US,fr;q=0.6
Would give :
{
"population": 9042,
"name": Berlin,
// ...
}

Answer 2

It depends on your clients. If the clients are applications, then #Orabîg's answer is 100% correct. If your clients are web browers, though, you should track language as a user preference. The reason is that a user might be using a non-personal machine where the browser is set to a different language, and they may not know how to or be able to change that setting. Rather than forcing them to use an unfamiliar language, you build the preference into your API.
In that case, I would start with the language provided in Accept-Language until the user either identified themself. Once they are passing some identifying token in a header with each request, use that to figure out what language responses should be in.

Answer 3

Just to mention the related article of W3C about using headers for locale determination (not only language that seems be the original case of the question)
The HTTP Accept-Language header was originally only intended to specify the user's language. However, since many applications need to know the locale of the user, common practice has used Accept-Language to determine this information. It is not a good idea to use the HTTP Accept-Language header alone to determine the locale of the user. If you use Accept-Language exclusively, you may handcuff the user into a set of choices not to his liking.
For a first contact, using the Accept-Language value to infer regional settings may be a good starting point, but be sure to allow them to change the language as needed and specify their cultural settings more exactly if necessary. Store the results in a database or a cookie for later visits.
Some of the potential issues include the following:
Many users never change the defaults for Accept-Language. They are
set when the user agent is installed. Unless they are multilingual or
have some other reason to adjust language preferences they may not
even know such settings exist. Hence, the user may not have ever
ratified the Accept-Language setting.
A user agent may send a request
that specifies only a language and not a region, for example you may
not get a header with de-DE, de-CH or de-AT to indicate German as
spoken in Germany, Switzerland or Austria, respectively. On the other
hand, you might only get de indicating a preference for German. If
you were planning to use the region to decide what currency to use
you are now in a bind. Your particular circumstances might allow you
to make assumptions such as "Germany has 83 million people,
Switzerland has 7 million but only 63% speak German, Austria has 8
million, so this user probably uses the Euro. If we're wrong we'll
only offend 4.6% of our German speaking customers or just over 4
million people." Feel free to make such an assumption, if you can
accept the risk. Its a lot simpler to ask the user for more
information. Also, the math gets more difficult for Spanish or
English, for instance.
People borrow machines from friends, they rent
them from internet cafes. In these cases the inferred locale may be
inappropriate, and care should be taken to allow the user to select
the appropriate language and locale from whatever page they are
looking at.
Full article: Accept-Language used for locale setting