Supporting multiple languages in a REST API

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 APIs are based upon HTTP protocol, so they can use the headers, that are traditionally used to define the preferred 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,
   // ...
}

However, I would also consider the client's needs. If the client needs to collect all language variants, you can face possible optimization problems. In that case, the client needs to make as many API calls as the number of required languages.

The same issue could be faced in the case of creating the resource. If multiple languages are needed I would prefer the original variant:

"name": {
       "en": "Berlin",
       "nl": "Berlijn",
       // ...
   },

or

"city_names": [{
       "language_code": "en",
       "value": "Berin"
   }],