Supporting multiple languages in a REST API

问题

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?

回答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,
   // ...
}

回答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.

回答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

来源：https://stackoverflow.com/questions/25353854/supporting-multiple-languages-in-a-rest-api

标签

rest

asp.net-web-api