REST API request with language and region

Question

I'm developing a REST API and I need to implement a method which needs language and country to produce result in the correct format since the result contains numbers and dates.

I was using the HTTP Accept-Language header to get the language. The specs define the header as a language specifier, but now I'm not sure if it is correct to use this header for getting the country. For example, I want to allow a result in Spanish language but with numbers in English format (with commas instead of dots).

Is es-US an accepted value for the Accept-Language header?

I was thinking that I could develop a new custom header like X-Country for my REST API.

Any thoughts? Thanks.

Answer 1

There are good documents out there on how to localize your APIs. There is even a stack overflow response about it.

Mostly it revolves around content negotiation and the "Accept-Language" header. If you need to have currency managed separately, the general consensus seems to keep in in the payload rather then in headers, but if you are going to do headers I would do X-Accept-Currency (behaving akin to the other HTTP Accept headers, but with ISO 4217 currency codes) on the request, and X-Content-Currency on the response.

UPDATE: Things have changed - if you intend to submit your header for standardization, you should not prefix it with X.

Answer 2

I was thinking that I could develop a new custom header like X-Country for my REST API.

I would avoid custom headers if one of the standard HTTP headers suit your needs.

Is es-US an accepted value for Accept-Language header?

Yes, es-US (Spanish / United States) is a valid locale ^{(see the notes below)} and it's a suitable value for the Accept-Language header:

5.3.5. Accept-Language

The Accept-Language header field can be used by user agents to indicate the set of natural languages that are preferred in the response. Language tags are defined in Section 3.1.3.1. [...]

The relevant parts of the section 3.1.3.1 are quoted below:

3.1.3.1. Language Tags

A language tag, as defined in RFC 5646, identifies a natural language spoken, written, or otherwise conveyed by human beings for communication of information to other human beings. Computer languages are explicitly excluded. [...]

A language tag is a sequence of one or more case-insensitive subtags, each separated by a hyphen character (-, %x2D). In most cases, a language tag consists of a primary language subtag that identifies a broad family of related languages (e.g., en = English), which is optionally followed by a series of subtags that refine or narrow that language's range (e.g., en-CA = the variety of English as communicated in Canada). Whitespace is not allowed within a language tag. Example tags include:

fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN

See RFC 5646 for further information.

---

^{Note 1: The combinations of language and territory codes that can be considered valid (in the sense that a given population of a given territory is able to read and write a given language, and is comfortable enough to use it with computers) can be found here.}

^{Note 2: Not sure which programming language you are using, but here's the list of locales available in Java.}

Answer 3

Any thoughts? Thanks.

My recommendation would be to start from having a resource for each (language, country) that you support, then worry about whether you want to have a single resource that does content negotiation.

A simple pattern for a resource that uses content negotiation would be to use the Content-Location header to point back to the specific resource for the negotiated language/country pair.

See also Tom Christie's answer from 2012, especially the link to Fielding's comment in 2006